{"title":"FAQ API","slug":"api-faq","category":"faq","summary":"Questions courantes sur l'API — auth, limites de débit, gestion des erreurs, découverte d'endpoints.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":473,"read_minutes":2,"lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# FAQ API\n\nQuestions courantes sur l'API Synapse.\n\n## Comment m'authentifier ?\n\nDeux méthodes :\n\n1. **Mind Key** (pour les endpoints de données) : `Authorization: Bearer mk_...`\n2. **JWT** (pour les endpoints de compte) : `Authorization: Bearer eyJ...`\n\nOu via paramètre de requête (limite 60 req/min) : `?key=mk_...`\n\nVoir [Authentification](/docs/getting-started/authentication).\n\n## Quelle est la différence entre Mind Key et JWT ?\n\n- **Mind Key** : limitée au tenant, n'expire jamais, pour les données memory/chat/tasks\n- **JWT** : limitée à l'utilisateur, expire en 7 jours, pour la gestion compte/mind\n\nVoir [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Pourquoi est-ce que je reçois 401 Unauthorized ?\n\nCauses courantes :\n\n1. En-tête `Authorization` manquant\n2. Mind Key invalide (vérifiez qu'elle commence par `mk_`)\n3. Utilisation d'un JWT là où une Mind Key est requise (ou inversement)\n4. La Mind Key a été révoquée\n\n**Correction :** Vérifiez votre jeton. Voir [Authentification](/docs/getting-started/authentication).\n\n## Pourquoi est-ce que je reçois 404 Not Found ?\n\nVous avez utilisé un mauvais chemin d'endpoint. Synapse ne possède que les chemins\nlistés dans `GET /endpoints`.\n\n**Correction :** Appelez `GET /endpoints` pour voir tous les chemins valides. Ne\ndevinez pas.\n\n## Pourquoi est-ce que je reçois 429 Too Many Requests ?\n\nVous utilisez l'authentification par paramètre de requête `?key=`, qui est limitée à\n60/min.\n\n**Correction :** Passez à l'en-tête `Authorization: Bearer` (sans limite de débit).\n\nVoir [Limites de débit](/docs/api/rate-limits).\n\n## Comment lister tous les endpoints ?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Comment trouver le bon endpoint ?\n\n1. Vérifiez `GET /endpoints` pour la liste lisible par machine\n2. Vérifiez `GET /help` pour la documentation complète de l'API\n3. Parcourez `GET /docs` pour le système de documentation\n4. Utilisez `GET /openapi.json` pour la spécification OpenAPI 3.0\n\n## Puis-je utiliser GET au lieu de POST ?\n\nCertains endpoints POST ont des équivalents GET pour les outils n'utilisant que des\nURLs :\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nVérifiez `GET /endpoints` pour les variantes GET disponibles.\n\n## Comment gérer les erreurs ?\n\nToutes les erreurs renvoient du JSON :\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\nVoir [Erreurs & gestion des erreurs](/docs/api/errors).\n\n## Quelle est la limite de corps de requête ?\n\n10 Mo. Pour les payloads plus volumineux (ex. envoi de fichiers), utilisez les\nendpoints multipart.\n\n## L'API prend-elle en charge CORS ?\n\nOui. Tous les endpoints renvoient :\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT\n```\n\n## Y a-t-il un SDK ?\n\nOui :\n\n- **Node.js** : `npm install synapse-memory-sdk`\n- **MCP** : `npx -y synapse-mcp-api@latest`\n\nVoir [Vue d'ensemble de l'API](/docs/api/overview) pour plus de détails.\n\n## Comment paginer ?\n\nUtilisez `?limit=` et `?offset=` :\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nLimite par défaut : 100. Max : 500.\n\n## Puis-je filtrer les mémoires par catégorie ou tag ?\n\nOui :\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Comment rechercher des mémoires ?\n\nDeux façons :\n\n1. **Recherche par mots-clés FTS5** : `GET /memory/search?q=docker+swarm`\n2. **Recherche sémantique** : `GET /memory/semantic-search?q=container+orchestration`\n\nVoir [Recherche FTS5](/docs/concepts/fts5-search) et [Recherche sémantique](/docs/concepts/semantic-search).\n\n## Comment mettre à jour une mémoire ?\n\nPOST `/memory` avec la même `category` + `key` — la mémoire existante est mise à\njour, pas dupliquée.\n\n```bash\n# Stockage initial\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Mise à jour (même clé)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Comment supprimer une mémoire ?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Puis-je supprimer en masse ?\n\nOui :\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Prochaines étapes\n\n- [Vue d'ensemble de l'API](/docs/api/overview)\n- [Erreurs & gestion des erreurs](/docs/api/errors)\n- [Authentification](/docs/getting-started/authentication)\n","content_html":"

FAQ API

\n

Questions courantes sur l'API Synapse.

\n

Comment m'authentifier ?

\n

Deux méthodes :

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

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

\n

Voir Authentification.

\n

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

\n\n

Voir Mind Key vs JWT.

\n

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

\n

Causes courantes :

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

Correction : Vérifiez votre jeton. Voir Authentification.

\n

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

\n

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

\n

Correction : Appelez GET /endpoints pour voir tous les chemins valides. Ne\ndevinez pas.

\n

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

\n

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

\n

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

\n

Voir Limites de débit.

\n

Comment lister tous les endpoints ?

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

Comment trouver le bon endpoint ?

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

Puis-je utiliser GET au lieu de POST ?

\n

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

\n\n

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

\n

Comment gérer les erreurs ?

\n

Toutes les erreurs renvoient du JSON :

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

Voir Erreurs & gestion des erreurs.

\n

Quelle est la limite de corps de requête ?

\n

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

\n

L'API prend-elle en charge CORS ?

\n

Oui. Tous les endpoints renvoient :

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

Y a-t-il un SDK ?

\n

Oui :

\n\n

Voir Vue d'ensemble de l'API pour plus de détails.

\n

Comment paginer ?

\n

Utilisez ?limit= et ?offset= :

\n
curl ".../memory?limit=50&offset=100"

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

\n

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

\n

Oui :

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

Comment rechercher des mémoires ?

\n

Deux façons :

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

Voir Recherche FTS5 et Recherche sémantique.

\n

Comment mettre à jour une mémoire ?

\n

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

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

Comment supprimer une mémoire ?

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

Puis-je supprimer en masse ?

\n

Oui :

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

Prochaines étapes

\n\n","urls":{"html":"/docs/faq/api-faq","text":"/docs/faq/api-faq?format=text","json":"/docs/faq/api-faq?format=json","llm":"/docs/faq/api-faq?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}