{"title":"Vue d'ensemble de l'API & URL de base","slug":"overview","category":"api","summary":"Tous les endpoints de l'API Synapse, l'URL de base, les schémas d'authentification et les formats de réponse en un coup d'œil.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":615,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# Vue d'ensemble de l'API & URL de base\n\nL'API Synapse est une API HTTP RESTful. Tous les endpoints renvoient du JSON (sauf\nmention contraire). Cette page couvre l'essentiel à connaître avant d'explorer des\nendpoints spécifiques.\n\n## URL de base\n\n```\nhttps://synapse.schaefer.zone\n```\n\nTous les chemins de cette documentation sont relatifs à cette URL de base. Pour les\ninstances auto-hébergées, remplacez par votre propre URL.\n\n## Authentification\n\nDeux méthodes, toutes deux envoyées via l'en-tête `Authorization` :\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # pour les endpoints de données\nAuthorization: Bearer YOUR_JWT # pour les endpoints de compte\n```\n\nOu via un paramètre de requête (limité à 60/min) :\n\n```\n?key=YOUR_MIND_KEY\n```\n\nVoir [Authentification](/docs/getting-started/authentication) pour plus de détails.\n\n## Groupes d'endpoints\n\n| Groupe | Auth | Description |\n|-------|------|-------------|\n| Public | Aucune | Page d'accueil, santé, OpenAPI, docs |\n| Memory | Mind Key | CRUD, recherche, sync, embeddings |\n| Chat | Mind Key / JWT | Messagerie asynchrone entre humain et agent |\n| Tasks | Mind Key | Gestion des tâches |\n| Scripts | Mind Key / JWT | Stockage persistant de scripts |\n| Scheduler | Mind Key | Tâches cron + variables |\n| Webhooks | Mind Key | Rappels HTTP sur événements |\n| Computers | Mind Key / JWT | Contrôle à distance d'ordinateurs |\n| User/Minds | JWT | Compte + gestion des minds |\n| Sharing | JWT | Partage de minds entre utilisateurs |\n| Push | JWT | Abonnements Web Push |\n| Tools | Aucune | Heure, calculatrice, aléatoire (utilitaires publics) |\n\n## Formats de réponse\n\n- **JSON** (par défaut) : `{ \"key\": \"value\", ... }`\n- **Texte brut** : `/memory/recall` renvoie du texte optimisé pour les LLM\n- **HTML** : `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Enveloppe de réponse standard\n\nLes réponses de succès renvoient directement les données :\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nLes réponses d'erreur utilisent ce format :\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\n> [!NOTE]\n> Le champ `docs` renvoie vers la documentation pertinente pour les erreurs courantes.\n\n## Codes d'état HTTP\n\n| Code | Signification |\n|------|---------|\n| 200 | Succès (GET, PUT) |\n| 201 | Créé (POST) |\n| 204 | Aucun contenu (DELETE) |\n| 400 | Requête incorrecte (erreur de validation) |\n| 401 | Non autorisé (jeton manquant/invalide) |\n| 403 | Interdit (mauvais type de jeton) |\n| 404 | Introuvable (le chemin n'existe pas) |\n| 409 | Conflit (doublon) |\n| 429 | Trop de requêtes (limite de débit) |\n| 500 | Erreur serveur |\n\n## Endpoints de découvrabilité\n\n| Endpoint | Rôle |\n|----------|---------|\n| `GET /` | Page d'accueil (optimisée LLM) |\n| `GET /endpoints` | Liste lisible par machine de tous les endpoints |\n| `GET /endpoints?format=text` | Liste d'endpoints en texte brut |\n| `GET /openapi.json` | Spécification OpenAPI 3.0 |\n| `GET /help` | Documentation complète de l'API (HTML) |\n| `GET /help?format=json` | Docs de l'API en JSON |\n| `GET /docs` | Système de documentation (HTML) |\n| `GET /docs?format=json` | Index de documentation (JSON) |\n| `GET /docs?format=text&scope=all` | Toutes les docs en un bloc de texte |\n| `GET /playground` | Terrain de jeu interactif pour l'API |\n\n## Limites de débit\n\n| Méthode d'auth | Limite |\n|-------------|-------|\n| Mind Key (en-tête) | Aucune |\n| Mind Key (?key=) | 60/min par IP |\n| JWT (en-tête) | Aucune |\n| Endpoints publics | Aucune |\n\nLes réponses soumises à limite de débit incluent :\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (uniquement en cas de 429)\n```\n\n## Pagination\n\nLes endpoints de liste prennent en charge `?limit=` et `?offset=` :\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nLimite par défaut : 100. Limite maximale : 500.\n\n## CORS\n\nTous les endpoints prennent en charge CORS pour les clients basés sur navigateur :\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK & Clients\n\n- **SDK Node.js** : `npm install synapse-memory-sdk` ([dépôt](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **Serveur MCP** : `npx -y synapse-mcp-api@latest` ([dépôt](https://gitlab.com/schaefer-services/synapse-mcp))\n- **Client HTTP** : n'importe quelle bibliothèque HTTP (curl, fetch, axios, etc.)\n\n## Prochaines étapes\n\n- [API Memory](/docs/api/memory) — les endpoints les plus importants\n- [API Chat](/docs/api/chat) — communication asynchrone humain-agent\n- [Erreurs & gestion des erreurs](/docs/api/errors)\n","content_html":"

Vue d'ensemble de l'API & URL de base

\n

L'API Synapse est une API HTTP RESTful. Tous les endpoints renvoient du JSON (sauf\nmention contraire). Cette page couvre l'essentiel à connaître avant d'explorer des\nendpoints spécifiques.

\n

URL de base

\n
https://synapse.schaefer.zone

Tous les chemins de cette documentation sont relatifs à cette URL de base. Pour les\ninstances auto-hébergées, remplacez par votre propre URL.

\n

Authentification

\n

Deux méthodes, toutes deux envoyées via l'en-tête Authorization :

\n
Authorization: Bearer YOUR_MIND_KEY    # pour les endpoints de données\nAuthorization: Bearer YOUR_JWT          # pour les endpoints de compte

Ou via un paramètre de requête (limité à 60/min) :

\n
?key=YOUR_MIND_KEY

Voir Authentification pour plus de détails.

\n

Groupes d'endpoints

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GroupeAuthDescription
PublicAucunePage d'accueil, santé, OpenAPI, docs
MemoryMind KeyCRUD, recherche, sync, embeddings
ChatMind Key / JWTMessagerie asynchrone entre humain et agent
TasksMind KeyGestion des tâches
ScriptsMind Key / JWTStockage persistant de scripts
SchedulerMind KeyTâches cron + variables
WebhooksMind KeyRappels HTTP sur événements
ComputersMind Key / JWTContrôle à distance d'ordinateurs
User/MindsJWTCompte + gestion des minds
SharingJWTPartage de minds entre utilisateurs
PushJWTAbonnements Web Push
ToolsAucuneHeure, calculatrice, aléatoire (utilitaires publics)
\n

Formats de réponse

\n\n

Enveloppe de réponse standard

\n

Les réponses de succès renvoient directement les données :

\n
{ "id": "mem_001", "status": "stored" }

Les réponses d'erreur utilisent ce format :

\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}
Le champ `docs` renvoie vers la documentation pertinente pour les erreurs courantes.

Codes d'état HTTP

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CodeSignification
200Succès (GET, PUT)
201Créé (POST)
204Aucun contenu (DELETE)
400Requête incorrecte (erreur de validation)
401Non autorisé (jeton manquant/invalide)
403Interdit (mauvais type de jeton)
404Introuvable (le chemin n'existe pas)
409Conflit (doublon)
429Trop de requêtes (limite de débit)
500Erreur serveur
\n

Endpoints de découvrabilité

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointRôle
GET /Page d'accueil (optimisée LLM)
GET /endpointsListe lisible par machine de tous les endpoints
GET /endpoints?format=textListe d'endpoints en texte brut
GET /openapi.jsonSpécification OpenAPI 3.0
GET /helpDocumentation complète de l'API (HTML)
GET /help?format=jsonDocs de l'API en JSON
GET /docsSystème de documentation (HTML)
GET /docs?format=jsonIndex de documentation (JSON)
GET /docs?format=text&scope=allToutes les docs en un bloc de texte
GET /playgroundTerrain de jeu interactif pour l'API
\n

Limites de débit

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Méthode d'authLimite
Mind Key (en-tête)Aucune
Mind Key (?key=)60/min par IP
JWT (en-tête)Aucune
Endpoints publicsAucune
\n

Les réponses soumises à limite de débit incluent :

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (uniquement en cas de 429)

Pagination

\n

Les endpoints de liste prennent en charge ?limit= et ?offset= :

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

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

\n

CORS

\n

Tous les endpoints prennent en charge CORS pour les clients basés sur navigateur :

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

SDK & Clients

\n\n

Prochaines étapes

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