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

PATCH /api/auth/me accepte {"avatar": "<data-url>"} (PNG/JPEG/WebP, 400 000 caractères max, octets magiques contrôlés) ; {"avatar": ""} supprime la photo. La valeur est renvoyée par GET /api/auth/me et par le payload user du login.

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)

12 KiB Raw Blame History

🔌 Guide de l'API REST