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é.