ObsiGate/docs/GUIDES/API_REST.md

🔌 Guide de l'API REST

ObsiGate expose une API REST complète couvrant toute l'application : vaults, fichiers, recherche, sauvegardes, exports, IA, partage, webhooks et administration. Ce guide explique l'authentification, la création de clés et donne des exemples prêts à l'emploi.

Public : développeurs, intégrateurs, scripts d'automatisation Doc interactive : /docs (Swagger UI) · /redoc (ReDoc) · /openapi.json Voir aussi : Serveur MCP · Authentification & sécurité

---

1. Base et conventions

Élément	Valeur
URL de base	http://<hôte>:2020 (Docker) ou http://127.0.0.1:17890 (desktop)
Préfixe API	/api
Format	JSON (application/json)
Version	suit la version d'ObsiGate (header X-…, /api/health)
Erreurs	{"detail": "..."} + code HTTP (400, 401, 403, 404, 409, 422, 500)

Quand l'authentification est désactivée (OBSIGATE_AUTH_ENABLED=false), tous les endpoints sont accessibles sans jeton (utilisateur anonyme avec accès à tous les vaults).

---

2. Authentification

2.1 Jeton de session (JWT)

Obtenu via POST /api/auth/login. Le jeton d'accès a une durée de vie courte (OBSIGATE_ACCESS_TOKEN_TTL, défaut 3600 s) et un refresh token longue durée est posé en cookie HTTP-only.

curl -s -X POST http://localhost:2020/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"votre_mot_de_passe"}'

Réponse (extrait) :

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": { "username": "admin", "role": "admin", "vaults": ["*"] }
}

Deux façons de présenter le jeton :

Authorization: Bearer <access_token>

ou, pour un client navigateur, le cookie HTTP-only avec credentials: "include" (le login pose aussi un cookie access_token).

2.2 Clés API longue durée (recommandé pour scripts & MCP)

Une seule clé authentifie l'API REST et le serveur MCP. Créez-la depuis l'interface (Configurations → 🔑 Clés API & MCP) ou par API :

# 1. Se connecter, récupérer le token (section 2.1)
# 2. Créer une clé valable 30 jours
curl -s -X POST http://localhost:2020/api/auth/tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Script backup","expiry":"30d"}'

Réponse (token affiché une seule fois) :

{
  "token": "eyJ...",
  "jti": "…",
  "name": "Script backup",
  "created_at": 1790000000,
  "expires_at": 1792592000,
  "expiry_key": "30d"
}

expiry	Durée
1d	1 jour
30d	1 mois
180d	6 mois
365d	1 an
never	sans expiration

Gestion :

Endpoint	Rôle
GET /api/auth/tokens	Lister vos clés (last_used_at, statut)
POST /api/auth/tokens	Créer ({name, expiry})
DELETE /api/auth/tokens/{jti}	Révoquer immédiatement (API et MCP)

Le JWT brut n'est jamais persisté : copiez-le à la création. Plafond : 50 clés actives par utilisateur.

---

3. Référence des endpoints

Liste non exhaustive — la référence faisant foi est /openapi.json. Les colonnes Auth indiquent le niveau requis (—, Oui, Admin).

3.1 Système

Endpoint	Description	Méthode	Auth
/api/health	Santé (statut, version, stats)	GET	—
/api/health/detailed	Santé détaillée	GET	—
/api/config	Lire / écrire la configuration	GET/POST	Oui/Admin
/api/diagnostics	Statistiques index & mémoire	GET	Admin
/api/dashboard	Statistiques du tableau de bord	GET	Oui
/api/events	Flux SSE temps réel	GET	Oui

3.2 Vaults

Endpoint	Description	Méthode	Auth
/api/vaults	Liste (filtrée par permissions)	GET	Oui
/api/vaults/status	Statut de toutes les vaults	GET	Oui
/api/vaults/add	Ajouter une vault (volume déjà monté)	POST	Admin
/api/vaults/{name}	Supprimer une vault	DELETE	Admin
/api/index/reload	Réindexation complète	GET	Admin
/api/index/reload/{vault}	Réindexer une vault	GET	Oui
/api/vaults/{vault}/settings	Lire / écrire les réglages	GET/POST	Oui
/api/attachments/rescan/{vault}	Rescanner les attachements	POST	Oui

3.3 Fichiers

Endpoint	Description	Méthode	Auth
/api/browse/{vault}?path=	Naviguer dans les dossiers	GET	Oui
/api/file/{vault}?path=	Contenu rendu (Markdown)	GET	Oui
/api/file/{vault}/raw?path=	Contenu brut	GET	Oui
/api/file/{vault}/download?path=	Télécharger	GET	Oui
/api/file/{vault}/save?path=	Enregistrer	PUT	Oui
/api/file/{vault}	Créer	POST	Oui
/api/file/{vault}	Renommer	PATCH	Oui
/api/file/{vault}	Supprimer	DELETE	Oui
/api/directory/{vault}	Créer / renommer / supprimer un dossier	POST/PATCH/DELETE	Oui
/api/move/{vault}	Déplacer un fichier/dossier	POST	Oui
/api/vault/{vault}/batch-upload	Upload multiple (multipart)	POST	Oui
/api/image/{vault}?path=	Servir une image	GET	Oui

3.4 Recherche & graphe

Endpoint	Description	Méthode	Auth
/api/search	Recherche simple (legacy)	GET	Oui
/api/search/advanced	Recherche TF-IDF avancée (facettes, tri, pagination, semantic=)	GET	Oui
/api/search/replace	Recherche/remplacement multi-fichiers	POST	Oui
/api/tags?vault=	Tags uniques avec compteurs	GET	Oui
/api/suggest?q=	Autocomplétion de titres	GET	Oui
/api/tags/suggest?q=	Autocomplétion de tags	GET	Oui
/api/tree-search	Recherche de fichiers/dossiers	GET	Oui
/api/vault/{vault}/paths	Liste de chemins	GET	Oui
/api/graph/{vault}	Graphe de liens	GET	Oui

3.5 Sauvegardes

Endpoint	Description	Méthode	Auth
/api/file/{vault}/backups	Backups d'un fichier	GET	Oui
/api/file/{vault}/diff	Diff avec une version	GET	Oui
/api/file/{vault}/restore	Restaurer une version	POST	Oui
/api/backups	Lister les backups	GET	Oui
/api/backups/content	Contenu d'un backup	GET	Oui
/api/backups/delete / /purge / /compress / /auto	Gestion & purge	POST	Oui

3.6 Exports

Endpoint	Description	Méthode
/api/export/html	Exporter en HTML	GET
/api/export/md-bundle	Exporter en bundle Markdown (ZIP)	GET
/api/export/epub	Exporter en ePub	GET
/api/guide/download?format=md|pdf&lang=fr|en	Télécharger le guide intégré	GET

3.7 PDF

Endpoint	Description	Méthode
/api/file/{vault}/pdf/info	Métadonnées sans transfert	GET
/api/file/{vault}/pdf/stream	Streaming (HTTP Range, 206)	GET

3.8 IA

Endpoint	Description	Méthode
/api/ai/status	Statut des fournisseurs	GET
/api/ai/improve, /fix-spelling, /summarize, /translate, /rewrite, /to-list, /to-table, /frontmatter, /inline-complete, /to-canvas…	Actions éditeur IA	POST
/api/ai/model-capabilities?provider=&model=	Capacités d'un modèle	GET
/api/ai/bookslm/*	Console IA par répertoire	POST/GET
/api/ai/skills	Lister / créer / supprimer des skills	GET/POST/DELETE
/api/config/ai-keys · /api/config/tool-keys	Clés fournisseurs & sources	GET/POST/DELETE

3.9 Authentification & administration

Endpoint	Description	Méthode	Auth
/api/auth/status	Statut de l'auth	GET	—
/api/auth/login · /refresh · /logout	Cycle de session	POST	— / Cookie / Oui
/api/auth/me	Profil courant	GET/PATCH	Oui
/api/auth/change-password	Changer le mot de passe	POST	Oui
/api/auth/mfa/*	TOTP, WebAuthn, recovery	POST/GET	Oui
/api/auth/tokens	Clés API (voir §2.2)	GET/POST/DELETE	Oui
/api/auth/admin/users	Lister / créer des utilisateurs	GET/POST	Admin
/api/auth/admin/users/{u}	Modifier / supprimer	PATCH/DELETE	Admin
/api/admin/stats · /audit · /backup-stats · /stream	Monitoring admin	GET	Admin

3.10 Partage, webhooks, conflits, plugins, push

Endpoint	Description	Méthode
/api/share/{vault}	Créer un lien de partage public	POST
/api/shares	Lister / supprimer les partages	GET/DELETE
/api/webhooks	CRUD webhooks (HMAC-SHA256)	GET/POST/PATCH/DELETE
/api/conflicts · /api/conflicts/resolve	Conflits Syncthing	GET/POST
/api/plugins	Installer / activer / désactiver	GET/POST/DELETE
/api/push/*	Abonnement Web Push (VAPID)	GET/POST/DELETE

---

4. Exemples curl

BASE=http://localhost:2020
TOKEN=$(curl -s -X POST $BASE/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}' | jq -r .access_token)

# Santé
curl -s $BASE/api/health

# Lister les vaults
curl -s $BASE/api/vaults -H "Authorization: Bearer $TOKEN"

# Naviguer
curl -s "$BASE/api/browse/Recettes?path=" -H "Authorization: Bearer $TOKEN"

# Lire un fichier (rendu Markdown)
curl -s "$BASE/api/file/Recettes?path=pizza.md" -H "Authorization: Bearer $TOKEN"

# Lire en brut
curl -s "$BASE/api/file/Recettes/raw?path=pizza.md" -H "Authorization: Bearer $TOKEN"

# Sauvegarder
curl -s -X PUT "$BASE/api/file/Recettes/save?path=pizza.md" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"content":"# Pizza\n\nNouvelle recette."}'

# Recherche avancée
curl -s "$BASE/api/search/advanced?q=tag:cuisine%20pizza&vault=all&limit=20&offset=0&sort=relevance" \
  -H "Authorization: Bearer $TOKEN"

# Autocomplétion
curl -s "$BASE/api/suggest?q=piz&vault=all" -H "Authorization: Bearer $TOKEN"

# Forcer une réindexation
curl -s $BASE/api/index/reload -H "Authorization: Bearer $TOKEN"

Le mot de passe peut aussi être fourni par une clé API dans Authorization. Quand l'auth est désactivée, omettez l'en-tête.

---

5. Temps réel

5.1 SSE — /api/events

Flux d'événements de changement d'index (fichiers créés/supprimés/modifiés), avec reconnexion automatique côté client.

curl -N "$BASE/api/events"

5.2 WebSocket — collaboration

ws(s)://<hôte>/ws/collab/{vault}/{path} transporte les mises à jour Yjs/CRDT et la présence (curseurs distants). Authentification par cookie access_token ou paramètre ?token=, avec contrôle d'accès par vault. Voir Édition & collaboration.

---

6. Limites et bonnes pratiques

• Rate limiting : les endpoints de login et les outils IA sont limités ; respectez retry_after en cas de 429.
• Permissions : chaque endpoint fichier vérifie l'accès au vault et rejette les chemins hors vault (path traversal).
• Clés API : préférez-les aux mots de passe pour les scripts ; révoquez-les dès qu'elles ne servent plus.
• Gros volumes : utilisez la pagination (limit/offset) et le streaming HTTP Range pour les PDF.
• Exports : md-bundle et epub renvoient un fichier binaire — utilisez -o avec curl.

---

7. Dépannage

Code	Cause probable
401	Jeton absent, expiré ou révoqué
403	Compte sans accès à cette vault / réservé admin
404	Vault, fichier ou chemin inexistant
409	Conflit (fichier déjà existant, etc.)
422	Corps de requête invalide (schéma Pydantic)
429	Rate limit dépassé — voir retry_after
501	Export PDF indisponible (WeasyPrint/GTK absent)