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.

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.

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.

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.

Comment lister tous les endpoints ?

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 :

{
  "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.

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 pour plus de détails.

Comment paginer ?

Utilisez ?limit= et ?offset= :

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 :

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 et Recherche sémantique.

Comment mettre à jour une mémoire ?

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

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

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

Puis-je supprimer en masse ?

Oui :

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

Prochaines étapes

• Vue d'ensemble de l'API
• Erreurs & gestion des erreurs
• Authentification