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

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

## URL de base

```
https://synapse.schaefer.zone
```

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

## Authentification

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

```
Authorization: Bearer YOUR_MIND_KEY    # pour les endpoints de données
Authorization: Bearer YOUR_JWT          # pour les endpoints de compte
```

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

```
?key=YOUR_MIND_KEY
```

Voir [Authentification](/docs/getting-started/authentication) pour plus de détails.

## Groupes d'endpoints

| Groupe | Auth | Description |
|-------|------|-------------|
| Public | Aucune | Page d'accueil, santé, OpenAPI, docs |
| Memory | Mind Key | CRUD, recherche, sync, embeddings |
| Chat | Mind Key / JWT | Messagerie asynchrone entre humain et agent |
| Tasks | Mind Key | Gestion des tâches |
| Scripts | Mind Key / JWT | Stockage persistant de scripts |
| Scheduler | Mind Key | Tâches cron + variables |
| Webhooks | Mind Key | Rappels HTTP sur événements |
| Computers | Mind Key / JWT | Contrôle à distance d'ordinateurs |
| User/Minds | JWT | Compte + gestion des minds |
| Sharing | JWT | Partage de minds entre utilisateurs |
| Push | JWT | Abonnements Web Push |
| Tools | Aucune | Heure, calculatrice, aléatoire (utilitaires publics) |

## Formats de réponse

- **JSON** (par défaut) : `{ "key": "value", ... }`
- **Texte brut** : `/memory/recall` renvoie du texte optimisé pour les LLM
- **HTML** : `/`, `/docs`, `/human`, `/support`, `/playground`

## Enveloppe de réponse standard

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

```json
{ "id": "mem_001", "status": "stored" }
```

Les réponses d'erreur utilisent ce format :

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

> [!NOTE]
> Le champ `docs` renvoie vers la documentation pertinente pour les erreurs courantes.

## Codes d'état HTTP

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

## Endpoints de découvrabilité

| Endpoint | Rôle |
|----------|---------|
| `GET /` | Page d'accueil (optimisée LLM) |
| `GET /endpoints` | Liste lisible par machine de tous les endpoints |
| `GET /endpoints?format=text` | Liste d'endpoints en texte brut |
| `GET /openapi.json` | Spécification OpenAPI 3.0 |
| `GET /help` | Documentation complète de l'API (HTML) |
| `GET /help?format=json` | Docs de l'API en JSON |
| `GET /docs` | Système de documentation (HTML) |
| `GET /docs?format=json` | Index de documentation (JSON) |
| `GET /docs?format=text&scope=all` | Toutes les docs en un bloc de texte |
| `GET /playground` | Terrain de jeu interactif pour l'API |

## Limites de débit

| Méthode d'auth | Limite |
|-------------|-------|
| Mind Key (en-tête) | Aucune |
| Mind Key (?key=) | 60/min par IP |
| JWT (en-tête) | Aucune |
| Endpoints publics | Aucune |

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

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (uniquement en cas de 429)
```

## Pagination

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

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

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

## CORS

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

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

## SDK & Clients

- **SDK Node.js** : `npm install synapse-memory-sdk` ([dépôt](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **Serveur MCP** : `npx -y synapse-mcp-api@latest` ([dépôt](https://gitlab.com/schaefer-services/synapse-mcp))
- **Client HTTP** : n'importe quelle bibliothèque HTTP (curl, fetch, axios, etc.)

## Prochaines étapes

- [API Memory](/docs/api/memory) — les endpoints les plus importants
- [API Chat](/docs/api/chat) — communication asynchrone humain-agent
- [Erreurs & gestion des erreurs](/docs/api/errors)