# API — Immbot AI

Toutes les routes sont sous `/api`. Auth par cookie de session httpOnly. Les mutations exigent la
même origine (défense CSRF) et renvoient `{error}` avec le statut HTTP approprié en cas d'échec.

## Authentification
| Route | Méthode | Corps / retour |
|---|---|---|
| `/auth/login` | POST | `{username, password}` → `{ok, mustChangePassword, role}` (429 après 8 échecs/15 min) |
| `/auth/register` | POST | `{username, displayName, email?, password, accessCode?, courses[]}` |
| `/auth/change-password` | POST | `{currentPassword, newPassword}` — révoque puis recrée la session |
| `/auth/logout` | POST | — |

## Chat
| Route | Méthode | Détail |
|---|---|---|
| `/chat` | POST | `{conversationId?, courseCode, message, model, mode, knowledgeMode, attachmentIds[], crossCourse?, regenerateOfMessageId?}` → **SSE** : `meta` (ids), `delta` (texte), `error`, `done` (contenu final, citations résolues, jetons, palier de coût, citations invalides neutralisées) |
| `/models` | GET | Modèles activés (capacités, palier de coût) + préréglages |
| `/conversations` | GET | Liste (`?q=` recherche, `?archived=1`) |
| `/conversations/[id]` | GET/PATCH/DELETE | Fil complet / renommer, dossier, épingler, archiver / supprimer |
| `/conversations/[id]/branch` | POST | `{upToMessageId}` → nouvelle conversation |
| `/messages/[id]` | PATCH | `{feedback?, flag?, flagReason?, save?}` |
| `/citations/[chunkId]` | GET | Panneau source (extrait, voisins) — contrôle d'accès par espace |
| `/uploads` | POST | multipart `file` (+`conversationId`) — types vérifiés par signature, texte extrait, indexé dans l'espace étudiant |
| `/announcements` | GET | Annonces actives des cours de l'utilisateur |

## Apprentissage (inscription au cours vérifiée partout)
| Route | Méthode | Détail |
|---|---|---|
| `/learning/[course]/overview` | GET | Maîtrise, série, stats, recommandations justifiées |
| `/learning/[course]/concepts` | GET | Nœuds (maîtrise, compteurs) + liens typés |
| `/learning/[course]/flashcards` | GET/POST | File dues+nouvelles / `create` ou `generate` (IA, RAG) |
| `/learning/flashcards/review` | POST | `{cardId, q:2-5, suspend?, favorite?}` — SM-2 + maîtrise |
| `/learning/quiz` | POST | actions `start` / `answer` (correction serveur + cahier d'erreurs) / `next` (adaptatif) / `finish` |
| `/learning/exams` | GET/POST | Liste+tentatives / `start`, `submit` (correction, analyse par concept et axe) |
| `/learning/[course]/plan` | GET/POST | Plan actif / `create` (génération), `toggle` (cocher) |
| `/learning/errors` | GET/PATCH | Cahier d'erreurs / statut ou suppression |
| `/learning/[course]/summaries` | GET/POST | Résumés / génération (scope semaine/concept/examen, style) avec citations validées |
| `/library` | GET/POST/DELETE | Bibliothèque personnelle |

## Administration (rôle instructor/admin ; admin pour les mutations sensibles)
| Route | Méthode | Détail |
|---|---|---|
| `/admin/overview` | GET | Usage, coûts (jour/mois/série 14 j), erreurs, santé |
| `/admin/models` | GET/POST | Registre complet (prix) / `override` (activer, favori, note), `presets` |
| `/admin/ingest` | GET/POST | Runs + documents / relance (`?force=1`) |
| `/admin/prompts` | GET/POST | Noms, contenu+historique (`?name=`) / nouvelle version |
| `/admin/announcements` | GET/POST | CRUD (`create/update/delete`) |
| `/admin/users` | GET/PATCH | Utilisateurs+journal / rôle, désactivation, reset (mot de passe temporaire), cours, sessions |
| `/admin/pedagogy` | GET | Agrégats anonymisés (seuil 3 étudiants), questions difficiles, signalements |
| `/admin/settings` | GET/POST | Budgets, intégrité, croisement inter-cours, partage |

## Mode « Cours interactif » et outils (function calling)

Quand le modèle choisi supporte les outils, le chat lui expose :
- **Outils de cours** (tous les modes sauf Général ; accès direct SANS base vectorielle) :
  `lister_seances`, `plan_seance` (sections + titres des diapositives), `lire_diapositives`
  (contenu complet d'une plage, max 12), `rechercher_cours` (FTS5). Tout contenu servi reçoit une
  balise `[Sx]` enregistrée dans le contexte → citations validées comme d'habitude.
- **Outils Web** (modes Cours interactif / Cours + général / Général, si `EXA_API_KEY` /
  `FIRECRAWL_API_KEY` sont configurées) : `recherche_web` (Exa) et `lire_page_web` (Firecrawl,
  Markdown). Les sources Web sont attribuées par URL, jamais mélangées aux citations de cours.

Le mode de connaissances `course-tools` (« Cours interactif ») part SANS extraits pré-récupérés :
le modèle explore lui-même (max 5 tours d'outils). Le flux SSE émet `{type:"tool", name, label}`
à chaque appel — affiché en direct dans l'interface — et `done` inclut `toolTrace` (persisté dans
`messages.tool_trace`).