334 lines
12 KiB
Markdown
334 lines
12 KiB
Markdown
# 🔌 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](./MCP.md) · [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md)
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
```bash
|
|
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) :
|
|
|
|
```json
|
|
{
|
|
"access_token": "eyJ...",
|
|
"token_type": "bearer",
|
|
"expires_in": 3600,
|
|
"user": { "username": "admin", "role": "admin", "vaults": ["*"] }
|
|
}
|
|
```
|
|
|
|
Deux façons de présenter le jeton :
|
|
|
|
```http
|
|
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 :
|
|
|
|
```bash
|
|
# 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**) :
|
|
|
|
```json
|
|
{
|
|
"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 |
|
|
| `/api/duplicates` · `/api/duplicates/merge` | Doublons : paires candidates, fusion (`confirm: true`) | GET/POST |
|
|
| `/api/notify/channels` · `/api/notify/test` | Notifications Discord/Telegram/SMTP/webhook (CRUD admin + test) | GET/POST/PATCH/DELETE |
|
|
| `/api/scheduler/tasks` · `/api/scheduler/tasks/{id}/run` | Tâches planifiées (CRUD + exécution manuelle) | GET/POST/PATCH/DELETE |
|
|
|
|
---
|
|
|
|
## 4. Exemples `curl`
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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](./COLLABORATION.md).
|
|
|
|
---
|
|
|
|
## 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) |
|