# 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).