API REST

API REST
Dernière mise à jour : 2026-05-10
34 endpoints, tous prefixés 
/api. Auth par cookie de session (HTTP-only). Validation Zod systématique.
Auth
Méthode
Path
Auth
Description
POST
/api/auth/register
Non
Crée user (username, email, password). Hash argon2id. Statut 
pending. Notif admin email
POST
/api/auth/login
Non
Login → session 7j. Rate-limit 5 tentatives / 15 min
POST
/api/auth/logout
Oui
Invalide la session
GET
/api/confirm-user/:token
Non
Email confirmation one-time → role 
user
Games
Méthode
Path
Auth
Description
GET
/api/games
Confirmed
Liste tous jeux + metadata BGG
GET
/api/games/:id
Confirmed
Détail jeu (rules_language, hasCardDatabase, etc.)
GET
/api/games/:id/pdf
Confirmed
Stream PDF (
Content-Type: application/pdf)
GET
/api/games/:id/page-image/:page
Confirmed
PNG 300 DPI page N (rendu via 
pdftoppm)
GET
/api/games/search?q=
Confirmed
Recherche fulltext (LIKE)
POST
/api/games/ingest
Confirmed + canAddGames
Multipart : PDF + metadata. Si 
scheduled_start_at : queue scheduled, sinon démarrage immédiat
DELETE
/api/games/:id
Admin
Supprime jeu, questions, purge collection Qdrant
DELETE
/api/games/:id/scheduled
Confirmed + canAddGames
Annule ingestion scheduled. 409 si pas en 
scheduled
Ask (RAG)
Méthode
Path
Auth
Description
POST
/api/ask/retrieve
Confirmed
Retrieval seul (chunks sans génération) — pour évaluation
POST
/api/ask/stream
Confirmed
RAG streaming SSE (question → retrieval → Claude). Body : 
{ game_id, question, extensions, history, cardMentions, stickyCardMentions }
GET
/api/ask/:questionId
Confirmed
Récupère la réponse persistée (fallback SSE après crash connexion)
PUT
/api/ask/:questionId/feedback
Confirmed
Vote pouce ↑↓ + comment
Cards
Méthode
Path
Auth
Description
GET
/api/cards/search?gameId=&q=&limit=
Confirmed
Autocomplete par collection (BM25 ou full-text)
GET
/api/cards/image/:pointId?w=&gameId=
Confirmed
Proxy image cachée (sharp resize, fallback CDN)
Decks
Méthode
Path
Auth
Description
POST
/api/decks/parse
Confirmed
Parse decklist texte → pointIds Qdrant. Whitelist 
flesh-and-blood-cards. Rate-limit 10/min
BGG
Méthode
Path
Auth
Description
GET
/api/bgg/hot
Confirmed
Top 20 jeux BGG (cache 6h)
GET
/api/bgg/search?q=
Confirmed
Recherche BGG XML API
GET
/api/bgg/game/:bggId
Confirmed
Détail jeu BGG
GET
/api/bgg/game/:bggId/expansions
Confirmed
Extensions d'un jeu BGG
Lorcana
Méthode
Path
Auth
Description
GET
/api/lorcana-symbols/:symbolId
Confirmed
SVG symboles spécialisés Lorcana
Admin
Méthode
Path
Auth
Description
GET
/api/admin/health
Admin
Health Qdrant, TEI, reranker, Claude SSH, SMTP + stats
GET
/api/admin/users
Admin
Liste users (id, username, role, canAddGames)
DELETE
/api/admin/users/:id
Admin
Supprime user + questions, réassigne ses jeux à l'admin
POST
/api/admin/users/:id/set-can-add-games
Admin
Toggle 
canAddGames
POST
/api/admin/confirm-user/:userId
Admin
Force confirmation user pending → role 
user
GET
/api/admin/feedback?gameId=&vote=&from=&to=&page=
Admin
Pagine feedbacks filtrés
GET
/api/admin/feedback/:id
Admin
Détail feedback + diagnostics complets
POST
/api/admin/feedback/export
Admin
Export CSV feedbacks filtrés
POST
/api/admin/games/:id/sync-cards
Admin
Force sync collection Qdrant vs source
GET
/api/admin/cards/list
Admin
Liste collections + counts
POST
/api/admin/send-test-email
Admin
Test SMTP
POST
/api/admin/send-password-reset/:userId
Admin
Force reset email
Health
Méthode
Path
Auth
Description
GET
/api/health
Non
{ status: 'ok', timestamp } (Docker healthcheck)
Patterns globaux
UUID v4 partout (
game_id, 
question_id, 
user_id)
Rate-limit ask : 20 questions/min/user
Rate-limit deck parse : 10/min/user
Rate-limit login : 5 tentatives → 15 min cooldown / IP
Limites taille : question ≤500 chars, comment ≤1000 chars, decklist ≤50 000 chars
SSE events : 
meta (1er, porte questionId), 
phase, 
context, 
token, 
done, 
error, 
quota_pause, 
heartbeat (8s)
Pas d'OpenAPI/Swagger — le tableau ci-dessus est la source de vérité.