# 🚀 Guide d'Utilisation

Bienvenue dans le guide officiel de votre **Homelab Automation Dashboard** !
Découvrez comment gérer et automatiser efficacement votre infrastructure grâce à cette solution puissante et centralisée.

---

## ⚡️ Démarrage Rapide {#help-quickstart}

<!-- quickstart-cards -->
:::card green fa-1
### Ajouter vos Hosts
Commencez par ajouter vos serveurs dans la section `Hosts`. Chaque host nécessite un nom, une adresse IP et un système d'exploitation.
:::

:::card blue fa-2
### Bootstrap Ansible
Exécutez le `Bootstrap` sur chaque host pour configurer l'accès SSH et les prérequis Ansible.
:::

:::card purple fa-3
### Automatiser
Utilisez les `Actions Rapides` ou exécutez des playbooks personnalisés pour automatiser vos tâches.
:::
<!-- /quickstart-cards -->

---

## ❤️‍🩹 Indicateurs de Santé des Hosts {#help-indicators}

Chaque host affiche un indicateur visuel de santé représenté par des barres colorées. Cet indicateur combine plusieurs facteurs pour évaluer l'état global de votre serveur.

### Comprendre l'Indicateur

:::health-level excellent 5 green
**Excellent** (5 barres vertes)
Host en ligne, bootstrap OK, vérifié récemment
:::

:::health-level good 3 yellow
**Bon** (3-4 barres jaunes)
Host fonctionnel mais certains aspects à améliorer
:::

:::health-level medium 2 orange
**Moyen** (2 barres oranges)
Attention requise - vérification recommandée
:::

:::health-level low 1 red
**Faible** (1 barre rouge)
Host hors ligne ou non configuré
:::

### Facteurs de Calcul du Score

:::score-factor fa-circle green +2 points
**Statut en ligne**
Le host répond aux requêtes réseau
:::

:::score-factor fa-check-circle blue +1 point
**Bootstrap Ansible OK**
SSH et prérequis Ansible configurés
:::

:::score-factor fa-clock purple +2 points
**Vérifié récemment (<1h)**
Dernière vérification il y a moins d'une heure
:::

:::score-factor fa-clock yellow +1 point
**Vérifié aujourd'hui**
Dernière vérification dans les 24 dernières heures
:::

> **Astuce:** Exécutez régulièrement un `Health Check` pour maintenir un score de santé élevé.

### Statuts Bootstrap Ansible

:::status-badge green fa-check-circle Ansible Ready
Le host est entièrement configuré pour Ansible. L'utilisateur automation existe, la clé SSH est déployée et sudo est configuré sans mot de passe.
:::

:::status-badge yellow fa-exclamation-triangle Non configuré
Le bootstrap n'a pas encore été exécuté sur ce host. Cliquez sur le bouton `Bootstrap` pour configurer l'accès Ansible.
:::

### Que signifie "Jamais vérifié" ?

Ce message apparaît lorsqu'aucun Health Check n'a été exécuté sur le host depuis son ajout. Le système ne peut pas déterminer l'état réel du serveur. Lancez un Health Check pour mettre à jour le statut et obtenir un score de santé précis.

---

## 🏗️ Architecture de la Solution {#help-architecture}

### Stack Technologique

- **Backend:** FastAPI (Python) - API REST haute performance {icon:fa-server color:green}
- **Automation:** Ansible - Gestion de configuration {icon:fa-cogs color:orange}
- **Frontend:** HTML/CSS/JS avec TailwindCSS {icon:fa-desktop color:blue}
- **Déploiement:** Docker & Docker Compose {icon:fab fa-docker color:cyan}
- **Temps réel:** WebSocket pour les mises à jour live {icon:fa-plug color:yellow}

### Structure des Fichiers

```
homelab-automation/
├── app/
│   ├── routes/             # Routes API FastAPI
│   ├── models/             # Modèles SQLAlchemy
│   ├── schemas/            # Schémas Pydantic
│   ├── services/           # Logique métier
│   ├── index.html          # Interface web
│   └── main.js             # Logique frontend
├── ansible/
│   ├── inventory/
│   │   ├── hosts.yml       # Inventaire des hosts
│   │   └── group_vars/     # Variables par groupe
│   └── playbooks/          # Playbooks Ansible
├── alembic/                # Migrations de base de données
├── data/                   # Base de données SQLite
├── tasks_logs/             # Logs des tâches
├── docker-compose.yml
└── Dockerfile
```

---

## ⚙️ Fonctionnalités Détaillées par Section {#help-features}

:::accordion fa-tachometer-alt purple Dashboard
Vue d'ensemble centralisée de votre infrastructure homelab.

- **Métriques en temps réel:** État des hosts (Online/Offline), statistiques des tâches (Succès/Échec).
- **Actions Rapides:** Accès immédiat aux opérations courantes (Mise à jour globale, Health Check général).
- **Aperçu des Hosts:** Liste condensée avec indicateurs de statut et OS pour une surveillance rapide.
- **Notifications:** Alertes visuelles sur les dernières activités importantes.
:::

:::accordion fa-server blue Hosts
Gestion complète du cycle de vie de vos serveurs.

- **Inventaire:** Ajout, modification et suppression de hosts avec détection d'OS.
- **Bootstrap Ansible:** Préparation automatique des serveurs (User, Clés SSH, Sudo).
- **Indicateurs de Santé:** Score de santé détaillé basé sur la connectivité et la configuration.
- **Actions Individuelles:** Exécution de playbooks spécifiques (Upgrade, Backup, Reboot) sur un host.
- **Détails Avancés:** Vue détaillée avec historique des tâches et logs spécifiques au host.
:::

:::accordion fa-book pink Playbooks
Bibliothèque et exécution de playbooks Ansible personnalisés.

- **Catalogue:** Liste de tous les playbooks disponibles dans votre répertoire.
- **Exécution Ciblée:** Lancement de playbooks sur des hosts spécifiques ou des groupes.
- **Logs en Direct:** Suivi temps réel de l'exécution Ansible (console output).
- **Historique:** Accès rapide aux résultats des exécutions précédentes.
:::

:::accordion fa-tasks green Tasks
Traçabilité complète de toutes les opérations d'automatisation.

- **Suivi d'État:** Visualisation instantanée (En cours, Succès, Échec).
- **Filtrage Avancé:** Recherche par statut, par date ou par type d'action.
- **Logs Détaillés:** Accès aux sorties standard et d'erreur pour le débogage.
- **Auto-refresh:** Mise à jour automatique des tâches en cours d'exécution.
:::

:::accordion fa-calendar-alt indigo Schedules
Planification automatisée des tâches récurrentes.

- **Planification Cron:** Configuration flexible de la fréquence d'exécution.
- **Tâches Récurrentes:** Backups quotidiens, Mises à jour hebdomadaires, Health Checks horaires.
- **Ciblage:** Définition des hosts ou groupes cibles pour chaque planification.
- **Gestion:** Activation, désactivation ou modification des planifications existantes.
:::

:::accordion fa-file-alt orange Logs
Journal technique des événements système.

- **Streaming WebSocket:** Arrivée des logs en temps réel sans rechargement de page.
- **Niveaux de Log:** Distinction claire entre Info, Warning et Error.
- **Export:** Possibilité de télécharger les logs pour analyse externe.
- **Rétention:** Gestion de l'historique et nettoyage des logs anciens.
:::

:::accordion fa-bell red Alertes
Centre de messages pour les événements importants.

- **Suivi:** Consultez les alertes récentes (succès/échec, changements d'état).
- **Lecture:** Les alertes peuvent être marquées comme lues pour garder une boîte de réception propre.
- **Notifications:** Certaines alertes peuvent déclencher des notifications ntfy (si activé).
:::

:::accordion fa-cog cyan Configuration
Paramètres de l'application et intégrations.

- **Paramètres applicatifs:** Options persistées (ex: collecte des métriques).
- **Notifications:** Configuration et test du service ntfy.
- **Sécurité:** Gestion du compte utilisateur (mot de passe) via l'écran utilisateur.
:::

---

## 🔔 Système de Notifications (ntfy) {#help-notifications}

Restez informé de l'état de votre infrastructure grâce au système de notifications intégré basé sur **ntfy**.

### Canaux & Configuration

Les notifications sont envoyées via le service ntfy, permettant de recevoir des alertes push sur mobile et desktop.

- **Push Mobile:** Via l'application ntfy (Android/iOS).
- **Web Push:** Notifications navigateur sur desktop.
- **Priorité:** Gestion des niveaux d'urgence (Low à High).

### Types d'Alertes

Vous recevez des notifications pour les événements critiques :

- ✅ Succès des Backups
- ❌ Échecs de Tâches
- ⚠️ Changements de Santé Host
- 🛠️ Fin de Bootstrap

---

## 📖 Playbooks Ansible Disponibles {#help-playbooks}

:::playbook fa-tools yellow bootstrap-host.yml
Configure un nouveau host pour Ansible: création utilisateur, clé SSH, sudo sans mot de passe.
**Requis avant toute autre opération**
:::

:::playbook fa-heartbeat green health-check.yml
Vérifie l'état de santé: CPU, RAM, disque, services critiques.
**Exécution rapide, non destructif**
:::

:::playbook fa-arrow-up blue system-upgrade.yml
Met à jour tous les paquets système (apt/yum/dnf selon l'OS).
**Peut nécessiter un redémarrage**
:::

:::playbook fa-save cyan backup-config.yml
Sauvegarde les fichiers de configuration importants (/etc, configs apps).
**Stockage local ou distant**
:::

---

## 🔗 Référence API {#help-api}

L'API REST est accessible sur le port configuré (par défaut `8000`). Tous les endpoints (sauf indications contraires) nécessitent un header d'authentification : `Authorization: Bearer <token>`.

### 📖 Exemples d'utilisation

:::accordion fa-terminal gray Ad-hoc
Exemples d'utilisation pour les endpoints de type **Ad-hoc**.

- **GET `/api/adhoc/categories`** : Récupère la liste des catégories de commandes ad-hoc.
```bash
curl -X GET "http://localhost:8000/api/adhoc/categories" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/adhoc/categories`** : Crée une nouvelle catégorie de commandes ad-hoc.
```bash
curl -X POST "http://localhost:8000/api/adhoc/categories" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **PUT `/api/adhoc/categories/{category_name}`** : Met à jour une catégorie existante.
```bash
curl -X PUT "http://localhost:8000/api/adhoc/categories/<category_name>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/adhoc/categories/{category_name}`** : Supprime une catégorie et déplace ses commandes vers 'default'.
```bash
curl -X DELETE "http://localhost:8000/api/adhoc/categories/<category_name>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/adhoc/history`** : Récupère l'historique des commandes ad-hoc.
```bash
curl -X GET "http://localhost:8000/api/adhoc/history" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/adhoc/history/{command_id}`** : Supprime une commande de l'historique.
```bash
curl -X DELETE "http://localhost:8000/api/adhoc/history/<command_id>" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/adhoc/history/{command_id}/category`** : Met à jour la catégorie d'une commande dans l'historique.
```bash
curl -X PUT "http://localhost:8000/api/adhoc/history/<command_id>/category" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-exclamation-triangle orange Alerts
Exemples d'utilisation pour les endpoints de type **Alerts**.

- **POST `/api/alerts`** : Crée une nouvelle alerte.
```bash
curl -X POST "http://localhost:8000/api/alerts" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/alerts`** : Récupère les alertes avec pagination.
```bash
curl -X GET "http://localhost:8000/api/alerts" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/alerts/mark-all-read`** : Marque toutes les alertes comme lues.
```bash
curl -X POST "http://localhost:8000/api/alerts/mark-all-read" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/alerts/unread-count`** : Récupère le nombre d'alertes non lues.
```bash
curl -X GET "http://localhost:8000/api/alerts/unread-count" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/alerts/{alert_id}`** : Supprime une alerte.
```bash
curl -X DELETE "http://localhost:8000/api/alerts/<alert_id>" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/alerts/{alert_id}/read`** : Marque une alerte comme lue.
```bash
curl -X POST "http://localhost:8000/api/alerts/<alert_id>/read" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-cogs red Ansible
Exemples d'utilisation pour les endpoints de type **Ansible**.

- **POST `/api/ansible/adhoc`** : Exécute une commande ad-hoc Ansible.
```bash
curl -X POST "http://localhost:8000/api/ansible/adhoc" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/ansible/bootstrap`** : Compat: Bootstrap un hôte via /api/ansible/bootstrap (historique UI).
```bash
curl -X POST "http://localhost:8000/api/ansible/bootstrap" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/ansible/execute`** : Exécute un playbook Ansible.
```bash
curl -X POST "http://localhost:8000/api/ansible/execute" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/ansible/groups`** : Récupère la liste des groupes Ansible.
```bash
curl -X GET "http://localhost:8000/api/ansible/groups" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/ansible/inventory`** : Récupère l'inventaire Ansible.
```bash
curl -X GET "http://localhost:8000/api/ansible/inventory" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/ansible/playbooks`** : Liste les playbooks Ansible disponibles.
```bash
curl -X GET "http://localhost:8000/api/ansible/playbooks" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/ansible/ssh-config`** : Diagnostic de la configuration SSH.
```bash
curl -X GET "http://localhost:8000/api/ansible/ssh-config" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-lock purple Auth
Exemples d'utilisation pour les endpoints de type **Auth**.

- **POST `/api/auth/login`** : Connexion via formulaire OAuth2 (form-urlencoded).
```bash
curl -X POST "http://localhost:8000/api/auth/login" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=admin&password=password"
```

- **POST `/api/auth/login/json`** : Connexion via JSON body.
```bash
curl -X POST "http://localhost:8000/api/auth/login/json" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=admin&password=password"
```

- **GET `/api/auth/me`** : Récupère les informations de l'utilisateur connecté.
```bash
curl -X GET "http://localhost:8000/api/auth/me" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/auth/password`** : Change le mot de passe de l'utilisateur connecté.
```bash
curl -X PUT "http://localhost:8000/api/auth/password" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/auth/setup`** : Crée le premier utilisateur admin (uniquement si aucun utilisateur n'existe).
```bash
curl -X POST "http://localhost:8000/api/auth/setup" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/auth/status`** : Vérifie le statut d'authentification et si le setup initial est requis.
```bash
curl -X GET "http://localhost:8000/api/auth/status" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-rocket yellow Bootstrap
Exemples d'utilisation pour les endpoints de type **Bootstrap**.

- **POST `/api/bootstrap`** : Bootstrap un hôte pour Ansible.
```bash
curl -X POST "http://localhost:8000/api/bootstrap" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/bootstrap/status`** : Récupère le statut de bootstrap de tous les hôtes.
```bash
curl -X GET "http://localhost:8000/api/bootstrap/status" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/bootstrap/status/{host_name}`** : Récupère le statut de bootstrap d'un hôte spécifique.
```bash
curl -X GET "http://localhost:8000/api/bootstrap/status/<host_name>" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/bootstrap/status/{host_name}`** : Définit manuellement le statut de bootstrap d'un hôte.
```bash
curl -X POST "http://localhost:8000/api/bootstrap/status/<host_name>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-book-medical rose Builtin Playbooks
Exemples d'utilisation pour les endpoints de type **Builtin Playbooks**.

- **GET `/api/builtin-playbooks`** : Liste tous les builtin playbooks disponibles.
```bash
curl -X GET "http://localhost:8000/api/builtin-playbooks" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/builtin-playbooks/collect-all`** : Collecte les métriques de tous les hôtes.
```bash
curl -X POST "http://localhost:8000/api/builtin-playbooks/collect-all" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/builtin-playbooks/execute`** : Exécute un builtin playbook sur une cible.
```bash
curl -X POST "http://localhost:8000/api/builtin-playbooks/execute" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/builtin-playbooks/execute-background`** : Exécute un builtin playbook en arrière-plan.
```bash
curl -X POST "http://localhost:8000/api/builtin-playbooks/execute-background" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/builtin-playbooks/{builtin_id}`** : Récupère les détails d'un builtin playbook.
```bash
curl -X GET "http://localhost:8000/api/builtin-playbooks/<builtin_id>" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-cog gray Config
Exemples d'utilisation pour les endpoints de type **Config**.

- **GET `/api/config`** : Récupère la configuration publique de l'application.
```bash
curl -X GET "http://localhost:8000/api/config" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/config/version`** : Retourne la version de l'application, Python, et l'uptime.
```bash
curl -X GET "http://localhost:8000/api/config/version" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fab fa-docker cyan Docker
Exemples d'utilisation pour les endpoints de type **Docker**.

- **GET `/api/docker/alerts`** : List Docker alerts.
```bash
curl -X GET "http://localhost:8000/api/docker/alerts" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/docker/alerts/{alert_id}/acknowledge`** : Acknowledge an alert.
```bash
curl -X POST "http://localhost:8000/api/docker/alerts/<alert_id>/acknowledge" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/docker/alerts/{alert_id}/close`** : Close an alert manually.
```bash
curl -X POST "http://localhost:8000/api/docker/alerts/<alert_id>/close" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/docker/collect-all`** : Collect Docker info from all enabled hosts.
```bash
curl -X POST "http://localhost:8000/api/docker/collect-all" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/docker/container-customizations`** : Mise à jour / consultation de la ressource.
```bash
curl -X GET "http://localhost:8000/api/docker/container-customizations" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/docker/container-customizations/{host_id}/{container_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X PUT "http://localhost:8000/api/docker/container-customizations/<host_id>/<container_id>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/docker/container-customizations/{host_id}/{container_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X DELETE "http://localhost:8000/api/docker/container-customizations/<host_id>/<container_id>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/docker/containers`** : List all containers across all Docker hosts.
```bash
curl -X GET "http://localhost:8000/api/docker/containers" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/docker/containers/{host_id}/{container_id}/inspect`** : Get detailed container information.
```bash
curl -X GET "http://localhost:8000/api/docker/containers/<host_id>/<container_id>/inspect" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/docker/containers/{host_id}/{container_id}/logs`** : Get container logs.
```bash
curl -X GET "http://localhost:8000/api/docker/containers/<host_id>/<container_id>/logs" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/docker/containers/{host_id}/{container_id}/redeploy`** : Redeploy a container by pulling latest image.
```bash
curl -X POST "http://localhost:8000/api/docker/containers/<host_id>/<container_id>/redeploy" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/docker/containers/{host_id}/{container_id}/remove`** : Remove a container (admin only).
```bash
curl -X POST "http://localhost:8000/api/docker/containers/<host_id>/<container_id>/remove" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/docker/containers/{host_id}/{container_id}/restart`** : Restart a container.
```bash
curl -X POST "http://localhost:8000/api/docker/containers/<host_id>/<container_id>/restart" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/docker/containers/{host_id}/{container_id}/start`** : Start a stopped container.
```bash
curl -X POST "http://localhost:8000/api/docker/containers/<host_id>/<container_id>/start" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/docker/containers/{host_id}/{container_id}/stop`** : Stop a running container.
```bash
curl -X POST "http://localhost:8000/api/docker/containers/<host_id>/<container_id>/stop" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/docker/hosts`** : List all hosts with Docker information.
```bash
curl -X GET "http://localhost:8000/api/docker/hosts" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/docker/hosts/{host_id}/collect`** : Force an immediate Docker collection on a host.
```bash
curl -X POST "http://localhost:8000/api/docker/hosts/<host_id>/collect" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/docker/hosts/{host_id}/containers`** : List containers for a host.
```bash
curl -X GET "http://localhost:8000/api/docker/hosts/<host_id>/containers" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/docker/hosts/{host_id}/enable`** : Enable or disable Docker monitoring on a host.
```bash
curl -X POST "http://localhost:8000/api/docker/hosts/<host_id>/enable" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/docker/hosts/{host_id}/images`** : List images for a host with usage information.
```bash
curl -X GET "http://localhost:8000/api/docker/hosts/<host_id>/images" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/docker/hosts/{host_id}/networks`** : Liste les réseaux Docker d'un hôte.
```bash
curl -X GET "http://localhost:8000/api/docker/hosts/<host_id>/networks" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/docker/hosts/{host_id}/volumes`** : List volumes for a host.
```bash
curl -X GET "http://localhost:8000/api/docker/hosts/<host_id>/volumes" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/docker/images/{host_id}/{image_id}`** : Remove a Docker image (admin only).
```bash
curl -X DELETE "http://localhost:8000/api/docker/images/<host_id>/<image_id>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/docker/stats`** : Get global Docker statistics.
```bash
curl -X GET "http://localhost:8000/api/docker/stats" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-star yellow Favorites
Exemples d'utilisation pour les endpoints de type **Favorites**.

- **GET `/api/favorites/containers`** : Mise à jour / consultation de la ressource.
```bash
curl -X GET "http://localhost:8000/api/favorites/containers" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/favorites/containers`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/favorites/containers" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/favorites/containers/{favorite_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X DELETE "http://localhost:8000/api/favorites/containers/<favorite_id>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/favorites/groups`** : Mise à jour / consultation de la ressource.
```bash
curl -X GET "http://localhost:8000/api/favorites/groups" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/favorites/groups`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/favorites/groups" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **PATCH `/api/favorites/groups/{group_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X PATCH "http://localhost:8000/api/favorites/groups/<group_id>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/favorites/groups/{group_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X DELETE "http://localhost:8000/api/favorites/groups/<group_id>" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-layer-group indigo Groups
Exemples d'utilisation pour les endpoints de type **Groups**.

- **GET `/api/groups`** : Récupère la liste de tous les groupes Ansible.
```bash
curl -X GET "http://localhost:8000/api/groups" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/groups`** : Crée un nouveau groupe.
```bash
curl -X POST "http://localhost:8000/api/groups" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/groups/{group_name}`** : Récupère les détails d'un groupe.
```bash
curl -X GET "http://localhost:8000/api/groups/<group_name>" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/groups/{group_name}`** : Renomme un groupe.
```bash
curl -X PUT "http://localhost:8000/api/groups/<group_name>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/groups/{group_name}`** : Supprime un groupe.
```bash
curl -X DELETE "http://localhost:8000/api/groups/<group_name>" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-heartbeat green Health
Exemples d'utilisation pour les endpoints de type **Health**.

- **GET `/api/health`** : Récupère les métriques système.
```bash
curl -X GET "http://localhost:8000/api/health" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/health/check-all`** : Exécute un health check sur tous les hôtes en parallèle.
```bash
curl -X POST "http://localhost:8000/api/health/check-all" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/health/global`** : Endpoint de healthcheck global utilisé par Docker.
```bash
curl -X GET "http://localhost:8000/api/health/global" \
```

- **POST `/api/health/refresh`** : Force le rechargement des hôtes depuis l'inventaire Ansible.
```bash
curl -X POST "http://localhost:8000/api/health/refresh" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/health/runtime`** : Runtime diagnostics (python executable, asyncssh availability).
```bash
curl -X GET "http://localhost:8000/api/health/runtime" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/health/{host_name}`** : Effectue un health check sur un hôte spécifique.
```bash
curl -X GET "http://localhost:8000/api/health/<host_name>" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-question-circle cyan Help
Exemples d'utilisation pour les endpoints de type **Help**.

- **GET `/api/help/catalog`** : Retourne un catalogue de tous les points d'entrée de l'API en format JSON.
```bash
curl -X GET "http://localhost:8000/api/help/catalog" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/help/content`** : Retourne le contenu HTML de la page d'aide généré depuis help.md.
```bash
curl -X GET "http://localhost:8000/api/help/content" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/help/documentation.md`** : Télécharge la documentation d'aide en format Markdown.
```bash
curl -X GET "http://localhost:8000/api/help/documentation.md" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/help/documentation.pdf`** : Télécharge la documentation d'aide en format PDF.
```bash
curl -X GET "http://localhost:8000/api/help/documentation.pdf" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-server blue Hosts
Exemples d'utilisation pour les endpoints de type **Hosts**.

- **GET `/api/hosts`** : Récupère la liste des hôtes.
```bash
curl -X GET "http://localhost:8000/api/hosts" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/hosts`** : Crée un nouvel hôte.
```bash
curl -X POST "http://localhost:8000/api/hosts" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/hosts/by-name/{host_name}`** : Récupère un hôte par son nom.
```bash
curl -X GET "http://localhost:8000/api/hosts/by-name/<host_name>" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/hosts/by-name/{host_name}`** : Supprime un hôte par son nom.
```bash
curl -X DELETE "http://localhost:8000/api/hosts/by-name/<host_name>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/hosts/groups`** : Récupère la liste des groupes disponibles pour les hôtes.
```bash
curl -X GET "http://localhost:8000/api/hosts/groups" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/hosts/refresh`** : Force le rechargement des hôtes depuis l'inventaire Ansible.
```bash
curl -X POST "http://localhost:8000/api/hosts/refresh" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/hosts/sync`** : Synchronise les hôtes depuis l'inventaire Ansible vers la base de données.
```bash
curl -X POST "http://localhost:8000/api/hosts/sync" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/hosts/{host_id}`** : Récupère un hôte par son ID.
```bash
curl -X GET "http://localhost:8000/api/hosts/<host_id>" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/hosts/{host_id}`** : Supprime un hôte par son ID.
```bash
curl -X DELETE "http://localhost:8000/api/hosts/<host_id>" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/hosts/{host_name}`** : Met à jour un hôte existant.
```bash
curl -X PUT "http://localhost:8000/api/hosts/<host_name>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-broom indigo Lint
Exemples d'utilisation pour les endpoints de type **Lint**.

- **GET `/api/playbooks/results`** : Récupère tous les résultats de lint stockés en base de données.
```bash
curl -X GET "http://localhost:8000/api/playbooks/results" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/playbooks/results/{filename}`** : Récupère le dernier résultat de lint pour un playbook spécifique.
```bash
curl -X GET "http://localhost:8000/api/playbooks/results/<filename>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/playbooks/rules`** : Liste les règles ansible-lint disponibles.
```bash
curl -X GET "http://localhost:8000/api/playbooks/rules" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/playbooks/{filename}/lint`** : Exécute ansible-lint sur le contenu d'un playbook.
```bash
curl -X POST "http://localhost:8000/api/playbooks/<filename>/lint" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-file-alt orange Logs
Exemples d'utilisation pour les endpoints de type **Logs**.

- **GET `/api/logs`** : Récupère les logs récents avec filtrage optionnel.
```bash
curl -X GET "http://localhost:8000/api/logs" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/logs`** : Ajoute une nouvelle entrée de log.
```bash
curl -X POST "http://localhost:8000/api/logs" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/logs`** : Efface tous les logs (attention: opération destructive).
```bash
curl -X DELETE "http://localhost:8000/api/logs" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-chart-line purple Metrics
Exemples d'utilisation pour les endpoints de type **Metrics**.

- **GET `/api/monitoring`** : Récupère les métriques système globales.
```bash
curl -X GET "http://localhost:8000/api/monitoring" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/monitoring/all-hosts`** : Récupère les métriques de tous les hôtes.
```bash
curl -X GET "http://localhost:8000/api/monitoring/all-hosts" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/monitoring/collection-schedule`** : Récupère l'intervalle de collecte des métriques.
```bash
curl -X GET "http://localhost:8000/api/monitoring/collection-schedule" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/monitoring/collection-schedule`** : Définit l'intervalle de collecte des métriques.
```bash
curl -X POST "http://localhost:8000/api/monitoring/collection-schedule" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/monitoring/{host_id}`** : Récupère les métriques d'un hôte spécifique.
```bash
curl -X GET "http://localhost:8000/api/monitoring/<host_id>" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-bell red Notifications
Exemples d'utilisation pour les endpoints de type **Notifications**.

- **GET `/api/notifications/config`** : Récupère la configuration actuelle des notifications ntfy.
```bash
curl -X GET "http://localhost:8000/api/notifications/config" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/notifications/config`** : Met à jour la configuration des notifications ntfy.
```bash
curl -X PUT "http://localhost:8000/api/notifications/config" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/notifications/send`** : Envoie une notification personnalisée via ntfy.
```bash
curl -X POST "http://localhost:8000/api/notifications/send" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/notifications/test`** : Envoie une notification de test.
```bash
curl -X POST "http://localhost:8000/api/notifications/test" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/notifications/toggle`** : Active ou désactive les notifications ntfy.
```bash
curl -X POST "http://localhost:8000/api/notifications/toggle" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-book pink Playbooks
Exemples d'utilisation pour les endpoints de type **Playbooks**.

- **GET `/api/playbooks`** : Liste tous les playbooks avec métadonnées (taille, date, etc.).
```bash
curl -X GET "http://localhost:8000/api/playbooks" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/playbooks/{filename}`** : Supprime un playbook.
```bash
curl -X DELETE "http://localhost:8000/api/playbooks/<filename>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/playbooks/{filename}/content`** : Récupère le contenu d'un playbook (normal ou builtin).
```bash
curl -X GET "http://localhost:8000/api/playbooks/<filename>/content" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/playbooks/{filename}/content`** : Sauvegarde le contenu d'un playbook.
```bash
curl -X PUT "http://localhost:8000/api/playbooks/<filename>/content" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-calendar-alt indigo Schedules
Exemples d'utilisation pour les endpoints de type **Schedules**.

- **GET `/api/schedules`** : Liste tous les schedules.
```bash
curl -X GET "http://localhost:8000/api/schedules" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/schedules`** : Crée un nouveau schedule.
```bash
curl -X POST "http://localhost:8000/api/schedules" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/schedules/stats`** : Récupère les statistiques des schedules.
```bash
curl -X GET "http://localhost:8000/api/schedules/stats" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/schedules/upcoming`** : Récupère les prochaines exécutions planifiées.
```bash
curl -X GET "http://localhost:8000/api/schedules/upcoming" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/schedules/validate-cron`** : Valide une expression cron.
```bash
curl -X GET "http://localhost:8000/api/schedules/validate-cron" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/schedules/{schedule_id}`** : Récupère les détails d'un schedule.
```bash
curl -X GET "http://localhost:8000/api/schedules/<schedule_id>" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/schedules/{schedule_id}`** : Met à jour un schedule existant.
```bash
curl -X PUT "http://localhost:8000/api/schedules/<schedule_id>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/schedules/{schedule_id}`** : Supprime un schedule.
```bash
curl -X DELETE "http://localhost:8000/api/schedules/<schedule_id>" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/schedules/{schedule_id}/pause`** : Met en pause un schedule.
```bash
curl -X POST "http://localhost:8000/api/schedules/<schedule_id>/pause" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/schedules/{schedule_id}/resume`** : Reprend un schedule en pause.
```bash
curl -X POST "http://localhost:8000/api/schedules/<schedule_id>/resume" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/schedules/{schedule_id}/run`** : Exécute immédiatement un schedule.
```bash
curl -X POST "http://localhost:8000/api/schedules/<schedule_id>/run" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/schedules/{schedule_id}/runs`** : Récupère l'historique des exécutions d'un schedule.
```bash
curl -X GET "http://localhost:8000/api/schedules/<schedule_id>/runs" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-hdd blue Server
Exemples d'utilisation pour les endpoints de type **Server**.

- **GET `/api/server/logs`** : Récupère les logs serveur avec pagination.
```bash
curl -X GET "http://localhost:8000/api/server/logs" \
     -H "Authorization: Bearer <token>"
```
:::

:::accordion fa-tasks green Tasks
Exemples d'utilisation pour les endpoints de type **Tasks**.

- **GET `/api/tasks`** : Récupère la liste des tâches.
```bash
curl -X GET "http://localhost:8000/api/tasks" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/tasks`** : Crée une nouvelle tâche et exécute le playbook correspondant.
```bash
curl -X POST "http://localhost:8000/api/tasks" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/tasks/logs`** : Récupère les logs de tâches depuis les fichiers markdown.
```bash
curl -X GET "http://localhost:8000/api/tasks/logs" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/tasks/logs/dates`** : Récupère les dates disponibles pour le filtrage.
```bash
curl -X GET "http://localhost:8000/api/tasks/logs/dates" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/tasks/logs/stats`** : Récupère les statistiques des logs de tâches.
```bash
curl -X GET "http://localhost:8000/api/tasks/logs/stats" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/tasks/logs/{log_id}`** : Récupère le contenu d'un log de tâche spécifique.
```bash
curl -X GET "http://localhost:8000/api/tasks/logs/<log_id>" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/tasks/logs/{log_id}`** : Supprime un fichier de log de tâche.
```bash
curl -X DELETE "http://localhost:8000/api/tasks/logs/<log_id>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/tasks/running`** : Récupère les tâches en cours d'exécution.
```bash
curl -X GET "http://localhost:8000/api/tasks/running" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/tasks/{task_id}`** : Récupère une tâche spécifique.
```bash
curl -X GET "http://localhost:8000/api/tasks/<task_id>" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/tasks/{task_id}`** : Supprime une tâche.
```bash
curl -X DELETE "http://localhost:8000/api/tasks/<task_id>" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/tasks/{task_id}/cancel`** : Annule une tâche en cours d'exécution.
```bash
curl -X POST "http://localhost:8000/api/tasks/<task_id>/cancel" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-terminal gray Terminal
Exemples d'utilisation pour les endpoints de type **Terminal**.

- **POST `/api/terminal/cleanup`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/terminal/cleanup" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/terminal/command-history`** : Get command history globally (across all hosts).
```bash
curl -X GET "http://localhost:8000/api/terminal/command-history" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/terminal/command-history/purge`** : Purge command history older than specified days.
```bash
curl -X POST "http://localhost:8000/api/terminal/command-history/purge" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/terminal/connect/{session_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X GET "http://localhost:8000/api/terminal/connect/<session_id>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/terminal/popout/{session_id}`** : Serve the terminal popout page (fullscreen, minimal UI).
```bash
curl -X GET "http://localhost:8000/api/terminal/popout/<session_id>" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/terminal/proxy/{session_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X GET "http://localhost:8000/api/terminal/proxy/<session_id>" \
     -H "Authorization: Bearer <token>"
```

- **POST, PUT, DELETE, GET, PATCH `/api/terminal/proxy/{session_id}/{proxy_path:path}`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/terminal/proxy/<session_id>/<proxy_path:path>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/terminal/sessions/{session_id}`** : Mise à jour / consultation de la ressource.
```bash
curl -X DELETE "http://localhost:8000/api/terminal/sessions/<session_id>" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/terminal/sessions/{session_id}/close-beacon`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/terminal/sessions/<session_id>/close-beacon" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/terminal/sessions/{session_id}/command`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/terminal/sessions/<session_id>/command" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **POST `/api/terminal/sessions/{session_id}/heartbeat`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/terminal/sessions/<session_id>/heartbeat" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/terminal/sessions/{session_id}/probe`** : Mise à jour / consultation de la ressource.
```bash
curl -X GET "http://localhost:8000/api/terminal/sessions/<session_id>/probe" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/terminal/status`** : Mise à jour / consultation de la ressource.
```bash
curl -X GET "http://localhost:8000/api/terminal/status" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/terminal/{host_id}/command-history`** : Get command history for a specific host.
```bash
curl -X GET "http://localhost:8000/api/terminal/<host_id>/command-history" \
     -H "Authorization: Bearer <token>"
```

- **DELETE `/api/terminal/{host_id}/command-history`** : Clear command history for a specific host.
```bash
curl -X DELETE "http://localhost:8000/api/terminal/<host_id>/command-history" \
     -H "Authorization: Bearer <token>"
```

- **GET `/api/terminal/{host_id}/command-history/unique`** : Get unique commands for a host (deduplicated).
```bash
curl -X GET "http://localhost:8000/api/terminal/<host_id>/command-history/unique" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/terminal/{host_id}/command-history/{command_hash}/pin`** : Toggle the pinned status of a specific command across history.
```bash
curl -X POST "http://localhost:8000/api/terminal/<host_id>/command-history/<command_hash>/pin" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/terminal/{host_id}/shell-history`** : Get shell history directly from the remote host via SSH.
```bash
curl -X GET "http://localhost:8000/api/terminal/<host_id>/shell-history" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/terminal/{host_id}/terminal-sessions`** : Mise à jour / consultation de la ressource.
```bash
curl -X POST "http://localhost:8000/api/terminal/<host_id>/terminal-sessions" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```
:::

:::accordion fa-users purple Users
Exemples d'utilisation pour les endpoints de type **Users**.

- **GET `/api/users`** : Liste tous les utilisateurs (admin uniquement).
```bash
curl -X GET "http://localhost:8000/api/users" \
     -H "Authorization: Bearer <token>"
```

- **POST `/api/users`** : Crée un nouvel utilisateur (admin uniquement).
```bash
curl -X POST "http://localhost:8000/api/users" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **GET `/api/users/{user_id}`** : Récupère les détails d'un utilisateur (admin uniquement).
```bash
curl -X GET "http://localhost:8000/api/users/<user_id>" \
     -H "Authorization: Bearer <token>"
```

- **PUT `/api/users/{user_id}`** : Met à jour un utilisateur (admin uniquement).
```bash
curl -X PUT "http://localhost:8000/api/users/<user_id>" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

- **DELETE `/api/users/{user_id}`** : Désactive ou supprime un utilisateur (admin uniquement).
```bash
curl -X DELETE "http://localhost:8000/api/users/<user_id>" \
     -H "Authorization: Bearer <token>"
```
:::


## 🛠️ Dépannage {#help-troubleshooting}

:::troubleshoot Le bootstrap échoue avec "Permission denied"
**Cause:** Les identifiants SSH fournis sont incorrects ou l'utilisateur n'a pas les droits sudo.

**Solution:** Vérifiez le nom d'utilisateur et mot de passe. Assurez-vous que l'utilisateur peut exécuter `sudo` sur le host cible.
:::

:::troubleshoot Les hosts apparaissent "offline" alors qu'ils sont accessibles
**Cause:** Le health check n'a pas été exécuté ou la clé SSH n'est pas configurée.

**Solution:** Exécutez le bootstrap si ce n'est pas fait, puis lancez un Health Check.
:::

:::troubleshoot Les tâches restent bloquées "En cours"
**Cause:** Le processus Ansible peut être bloqué ou le host ne répond plus.

**Solution:** Vérifiez la connectivité réseau. Consultez les logs système pour plus de détails. Redémarrez le conteneur Docker si nécessaire.
:::

:::troubleshoot L'interface ne se met pas à jour en temps réel
**Cause:** La connexion WebSocket est interrompue.

**Solution:** Rafraîchissez la page. Vérifiez que le port WebSocket n'est pas bloqué par un firewall ou proxy.
:::

---

## ✨ Raccourcis & Astuces {#help-shortcuts}

### Navigation

- Cliquez sur le logo pour revenir au Dashboard
- Utilisez les onglets du menu pour naviguer
- Le thème clair/sombre est persistant

### Productivité

- Filtrez les hosts par groupe pour des actions groupées
- Utilisez les filtres de date pour retrouver des tâches
- Exportez les logs avant de les effacer

---

*Documentation générée par Homelab Automation Dashboard v1.0*