# FAQ API

Questions courantes sur l'API Synapse.

## Comment m'authentifier ?

Deux méthodes :

1. **Mind Key** (pour les endpoints de données) : `Authorization: Bearer mk_...`
2. **JWT** (pour les endpoints de compte) : `Authorization: Bearer eyJ...`

Ou via paramètre de requête (limite 60 req/min) : `?key=mk_...`

Voir [Authentification](/docs/getting-started/authentication).

## Quelle est la différence entre Mind Key et JWT ?

- **Mind Key** : limitée au tenant, n'expire jamais, pour les données memory/chat/tasks
- **JWT** : limitée à l'utilisateur, expire en 7 jours, pour la gestion compte/mind

Voir [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).

## Pourquoi est-ce que je reçois 401 Unauthorized ?

Causes courantes :

1. En-tête `Authorization` manquant
2. Mind Key invalide (vérifiez qu'elle commence par `mk_`)
3. Utilisation d'un JWT là où une Mind Key est requise (ou inversement)
4. La Mind Key a été révoquée

**Correction :** Vérifiez votre jeton. Voir [Authentification](/docs/getting-started/authentication).

## Pourquoi est-ce que je reçois 404 Not Found ?

Vous avez utilisé un mauvais chemin d'endpoint. Synapse ne possède que les chemins
listés dans `GET /endpoints`.

**Correction :** Appelez `GET /endpoints` pour voir tous les chemins valides. Ne
devinez pas.

## Pourquoi est-ce que je reçois 429 Too Many Requests ?

Vous utilisez l'authentification par paramètre de requête `?key=`, qui est limitée à
60/min.

**Correction :** Passez à l'en-tête `Authorization: Bearer` (sans limite de débit).

Voir [Limites de débit](/docs/api/rate-limits).

## Comment lister tous les endpoints ?

```bash
curl https://synapse.schaefer.zone/endpoints
curl https://synapse.schaefer.zone/endpoints?format=text
```

## Comment trouver le bon endpoint ?

1. Vérifiez `GET /endpoints` pour la liste lisible par machine
2. Vérifiez `GET /help` pour la documentation complète de l'API
3. Parcourez `GET /docs` pour le système de documentation
4. Utilisez `GET /openapi.json` pour la spécification OpenAPI 3.0

## Puis-je utiliser GET au lieu de POST ?

Certains endpoints POST ont des équivalents GET pour les outils n'utilisant que des
URLs :

- `POST /memory` ↔ `GET /memory/store?content=...`
- `POST /mind/task` ↔ `GET /mind/task?title=...`
- `POST /chat/reply` ↔ `GET /chat/reply?content=...`

Vérifiez `GET /endpoints` pour les variantes GET disponibles.

## Comment gérer les erreurs ?

Toutes les erreurs renvoient du JSON :

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

Voir [Erreurs & gestion des erreurs](/docs/api/errors).

## Quelle est la limite de corps de requête ?

10 Mo. Pour les payloads plus volumineux (ex. envoi de fichiers), utilisez les
endpoints multipart.

## L'API prend-elle en charge CORS ?

Oui. Tous les endpoints renvoient :

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT
```

## Y a-t-il un SDK ?

Oui :

- **Node.js** : `npm install synapse-memory-sdk`
- **MCP** : `npx -y synapse-mcp-api@latest`

Voir [Vue d'ensemble de l'API](/docs/api/overview) pour plus de détails.

## Comment paginer ?

Utilisez `?limit=` et `?offset=` :

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

Limite par défaut : 100. Max : 500.

## Puis-je filtrer les mémoires par catégorie ou tag ?

Oui :

```bash
curl ".../memory?category=project"
curl ".../memory?tag=docker"
curl ".../memory/by-tag?tag=production"
```

## Comment rechercher des mémoires ?

Deux façons :

1. **Recherche par mots-clés FTS5** : `GET /memory/search?q=docker+swarm`
2. **Recherche sémantique** : `GET /memory/semantic-search?q=container+orchestration`

Voir [Recherche FTS5](/docs/concepts/fts5-search) et [Recherche sémantique](/docs/concepts/semantic-search).

## Comment mettre à jour une mémoire ?

POST `/memory` avec la même `category` + `key` — la mémoire existante est mise à
jour, pas dupliquée.

```bash
# Stockage initial
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# Mise à jour (même clé)
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'
```

## Comment supprimer une mémoire ?

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

## Puis-je supprimer en masse ?

Oui :

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

## Prochaines étapes

- [Vue d'ensemble de l'API](/docs/api/overview)
- [Erreurs & gestion des erreurs](/docs/api/errors)
- [Authentification](/docs/getting-started/authentication)