{"nom":"API vibe-quiz","version":"1","description":"API REST de vibe-quiz, conçue pour être utilisée par une IA (Claude Code) sans aide humaine. Elle sert à créer et gérer les quiz d’un formateur, et à récupérer les résultats des sessions. Il n’y a pas d’éditeur de quiz dans l’interface : tout passe par cette API.","urlDeBase":"https://vibe-quiz.fr/api/v1","documentationLisible":"https://vibe-quiz.fr/documentation-api","authentification":{"type":"Bearer","entete":"Authorization: Bearer <votre clé>","obtenirUneCle":"https://vibe-quiz.fr/cles-api","remarque":"La clé commence par `vq_`. Elle donne accès aux seuls quiz et sessions de son formateur. Ne la mettez jamais dans un fichier versionné."},"limites":{"requetesParMinuteEtParCle":60,"depassement":"Réponse 429 avec l’en-tête `Retry-After` (en secondes)."},"formats":{"corps":"JSON (en-tête `Content-Type: application/json`), encodage UTF-8.","dates":"ISO 8601, en UTC.","quiz":{"titre":"texte, obligatoire, 120 caractères maximum","description":"texte ou null, facultatif, 1000 caractères maximum","questions":"liste de 1 à 100 questions, dans l’ordre de jeu"},"question":{"type":"\"qcm\" (facultatif, seule valeur disponible pour l’instant ; sondages, nuages de mots et échelles arriveront plus tard)","enonce":"texte, obligatoire, 300 caractères maximum","choix":"liste de 2 à 4 textes distincts, 120 caractères maximum chacun","bonneReponse":"entier, obligatoire : index de la bonne réponse dans `choix`, en comptant à partir de 0. Une seule bonne réponse par question.","duree":"entier, facultatif : temps de réponse en secondes, de 5 à 120 (20 par défaut)","explication":"texte ou null, facultatif, 500 caractères maximum : affichée à l’écran au moment de la révélation"},"conseils":["Gardez les énoncés et les choix courts : ils sont projetés sur grand écran et lus sur téléphone.","Variez la position de la bonne réponse d’une question à l’autre.","Les champs inconnus sont refusés : l’erreur indique les champs acceptés."]},"regleDuScore":"Bonne réponse : de 1000 points (réponse immédiate) à 500 points (dernière seconde), dégressif selon le temps mis. Mauvaise réponse ou absence de réponse : 0 point. L’heure de réponse est celle reçue par le serveur.","lienPartenaire":{"description":"Pour rattacher les scores à vos propres apprenants, générez un lien de connexion par apprenant avec le paramètre `ref` (200 caractères maximum). Il est invisible pour l’apprenant et renvoyé dans les résultats (`classement[].ref`).","modele":"https://vibe-quiz.fr/rejoindre/{code}?ref={identifiant-apprenant}","exemple":"https://vibe-quiz.fr/rejoindre/K7M2QX?ref=apprenant-4821"},"sessions":{"lancement":"Une session se lance depuis l’interface (bouton « Lancer une session »), pas depuis l’API.","code":"6 caractères, sans caractères ambigus (pas de 0/O, 1/I/L). Une session expire 24 heures après sa création.","participantsMaximum":50,"statuts":{"en_attente":"salle d’attente ouverte","en_cours":"partie en cours","terminee":"résultats disponibles"}},"erreurs":{"format":{"erreur":{"code":"validation","message":"Les données envoyées sont invalides. Corrigez les champs listés dans `details`.","details":[{"champ":"questions[3].choix","message":"4 choix maximum, 5 reçus."}]}},"codes":[{"statut":400,"code":"validation","signification":"Données invalides : `details` liste chaque champ fautif et la correction attendue."},{"statut":400,"code":"json_invalide","signification":"Le corps de la requête n’est pas du JSON valide."},{"statut":401,"code":"non_authentifie","signification":"Clé absente, invalide ou révoquée."},{"statut":404,"code":"introuvable","signification":"Quiz ou session inexistant dans votre compte."},{"statut":405,"code":"methode_non_autorisee","signification":"Méthode HTTP non prise en charge sur ce chemin."},{"statut":409,"code":"conflit","signification":"Action impossible dans l’état actuel."},{"statut":429,"code":"trop_de_requetes","signification":"Plus de 60 requêtes par minute : attendez le délai indiqué par `Retry-After`."},{"statut":500,"code":"erreur_serveur","signification":"Erreur inattendue : réessayez, puis signalez-la si elle persiste."}]},"actions":[{"id":"quiz-lister","methode":"GET","chemin":"/quiz","resume":"Lister vos quiz, du plus récemment modifié au plus ancien.","parametres":[{"nom":"limite","ou":"requete","type":"entier","obligatoire":false,"description":"Nombre maximum de quiz (1 à 200, 100 par défaut)."}],"reponse":{"statut":200,"exemple":{"quiz":[{"id":"javascript-les-bases-k3f9a","titre":"JavaScript : les bases","description":"Module 3 - variables et types","nombreQuestions":10,"nombreSessions":2,"creeLe":"2026-10-14T09:00:00.000Z","modifieLe":"2026-10-14T09:00:00.000Z","url":"https://vibe-quiz.fr/quiz/javascript-les-bases-k3f9a"}]}},"url":"https://vibe-quiz.fr/api/v1/quiz"},{"id":"quiz-creer","methode":"POST","chemin":"/quiz","resume":"Créer un quiz.","details":"Le quiz est prêt immédiatement dans le tableau de bord du formateur. L’`id` renvoyé sert à toutes les autres actions.","corps":{"titre":"JavaScript : les bases","description":"Module 3 - variables et types","questions":[{"type":"qcm","enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"duree":20,"explication":"`const` crée une liaison qui ne peut pas être réaffectée."}]},"reponse":{"statut":201,"exemple":{"quiz":{"id":"javascript-les-bases-k3f9a","titre":"JavaScript : les bases","description":"Module 3 - variables et types","nombreQuestions":1,"creeLe":"2026-10-14T09:00:00.000Z","modifieLe":"2026-10-14T09:00:00.000Z","url":"https://vibe-quiz.fr/quiz/javascript-les-bases-k3f9a","questions":[{"type":"qcm","enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"duree":20,"explication":"`const` crée une liaison qui ne peut pas être réaffectée."}]}}},"url":"https://vibe-quiz.fr/api/v1/quiz"},{"id":"quiz-lire","methode":"GET","chemin":"/quiz/{id}","resume":"Lire un quiz complet, avec ses questions et les bonnes réponses.","parametres":[{"nom":"id","ou":"chemin","type":"texte","obligatoire":true,"description":"Identifiant du quiz (champ `id`)."}],"reponse":{"statut":200,"exemple":{"quiz":{"id":"javascript-les-bases-k3f9a","titre":"JavaScript : les bases","description":"Module 3 - variables et types","nombreQuestions":1,"creeLe":"2026-10-14T09:00:00.000Z","modifieLe":"2026-10-14T09:00:00.000Z","url":"https://vibe-quiz.fr/quiz/javascript-les-bases-k3f9a","questions":[{"type":"qcm","enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"duree":20,"explication":"`const` crée une liaison qui ne peut pas être réaffectée."}]}}},"url":"https://vibe-quiz.fr/api/v1/quiz/{id}"},{"id":"quiz-remplacer","methode":"PUT","chemin":"/quiz/{id}","resume":"Remplacer entièrement un quiz (titre, description et toutes les questions).","details":"Même corps que la création. Les sessions déjà jouées gardent leurs questions d’origine.","parametres":[{"nom":"id","ou":"chemin","type":"texte","obligatoire":true,"description":"Identifiant du quiz."}],"corps":{"titre":"JavaScript : les bases (v2)","description":null,"questions":[{"type":"qcm","enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"duree":20,"explication":"`const` crée une liaison qui ne peut pas être réaffectée."}]},"reponse":{"statut":200,"exemple":{"quiz":{"id":"javascript-les-bases-k3f9a","titre":"JavaScript : les bases","description":"Module 3 - variables et types","nombreQuestions":1,"creeLe":"2026-10-14T09:00:00.000Z","modifieLe":"2026-10-14T09:00:00.000Z","url":"https://vibe-quiz.fr/quiz/javascript-les-bases-k3f9a","questions":[{"type":"qcm","enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"duree":20,"explication":"`const` crée une liaison qui ne peut pas être réaffectée."}]}}},"url":"https://vibe-quiz.fr/api/v1/quiz/{id}"},{"id":"quiz-modifier","methode":"PATCH","chemin":"/quiz/{id}","resume":"Modifier partiellement un quiz.","details":"Seuls les champs envoyés sont modifiés. Si `questions` est envoyé, la liste complète des questions est remplacée : pour corriger une seule question, lisez le quiz, modifiez la question, puis renvoyez toute la liste.","parametres":[{"nom":"id","ou":"chemin","type":"texte","obligatoire":true,"description":"Identifiant du quiz."}],"corps":{"titre":"JavaScript : les fondamentaux"},"reponse":{"statut":200,"exemple":{"quiz":{"id":"javascript-les-bases-k3f9a","titre":"JavaScript : les bases","description":"Module 3 - variables et types","nombreQuestions":1,"creeLe":"2026-10-14T09:00:00.000Z","modifieLe":"2026-10-14T09:00:00.000Z","url":"https://vibe-quiz.fr/quiz/javascript-les-bases-k3f9a","questions":[{"type":"qcm","enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"duree":20,"explication":"`const` crée une liaison qui ne peut pas être réaffectée."}]}}},"url":"https://vibe-quiz.fr/api/v1/quiz/{id}"},{"id":"quiz-supprimer","methode":"DELETE","chemin":"/quiz/{id}","resume":"Supprimer un quiz.","details":"Les résultats des sessions déjà jouées sont conservés.","parametres":[{"nom":"id","ou":"chemin","type":"texte","obligatoire":true,"description":"Identifiant du quiz."}],"reponse":{"statut":200,"exemple":{"supprime":true}},"url":"https://vibe-quiz.fr/api/v1/quiz/{id}"},{"id":"quiz-dupliquer","methode":"POST","chemin":"/quiz/{id}/dupliquer","resume":"Dupliquer un quiz (la copie s’appelle « … (copie) »).","parametres":[{"nom":"id","ou":"chemin","type":"texte","obligatoire":true,"description":"Identifiant du quiz à copier."}],"reponse":{"statut":201,"exemple":{"quiz":{"id":"javascript-les-bases-copie-p2x7d","titre":"JavaScript : les bases (copie)","description":"Module 3 - variables et types","nombreQuestions":1,"creeLe":"2026-10-14T09:00:00.000Z","modifieLe":"2026-10-14T09:00:00.000Z","url":"https://vibe-quiz.fr/quiz/javascript-les-bases-k3f9a","questions":[{"type":"qcm","enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"duree":20,"explication":"`const` crée une liaison qui ne peut pas être réaffectée."}]}}},"url":"https://vibe-quiz.fr/api/v1/quiz/{id}/dupliquer"},{"id":"sessions-lister","methode":"GET","chemin":"/sessions","resume":"Lister vos sessions (parties jouées ou en cours), de la plus récente à la plus ancienne.","parametres":[{"nom":"quiz","ou":"requete","type":"texte","obligatoire":false,"description":"Ne garder que les sessions de ce quiz (son `id`)."},{"nom":"depuis","ou":"requete","type":"date ISO 8601","obligatoire":false,"description":"Sessions créées à partir de cette date (ex. 2026-10-01)."},{"nom":"jusqua","ou":"requete","type":"date ISO 8601","obligatoire":false,"description":"Sessions créées jusqu’à cette date incluse."},{"nom":"limite","ou":"requete","type":"entier","obligatoire":false,"description":"Nombre maximum de sessions (1 à 200, 50 par défaut)."}],"reponse":{"statut":200,"exemple":{"sessions":[{"code":"K7M2QX","quiz":{"id":"javascript-les-bases-k3f9a","titre":"JavaScript : les bases"},"statut":"terminee","creeLe":"2026-10-14T13:30:00.000Z","termineeLe":"2026-10-14T13:48:12.000Z","nombreParticipants":24,"nombreQuestions":10,"scoreMoyen":6120,"lienRejoindre":"https://vibe-quiz.fr/rejoindre/K7M2QX"}]}},"url":"https://vibe-quiz.fr/api/v1/sessions"},{"id":"sessions-resultats","methode":"GET","chemin":"/sessions/{code}","resume":"Lire une session et ses résultats : classement final, score par participant et par question.","details":"Pour chaque participant : pseudo, identifiant externe `ref` s’il a été fourni dans le lien de connexion, score, rang, et pour chaque question le choix fait, juste ou faux, le temps de réponse et les points. Les résultats sont écrits à la fin de la session (ou 2 heures après la dernière activité si elle n’a pas été terminée). Alias : `/sessions/{code}/resultats`.","parametres":[{"nom":"code","ou":"chemin","type":"texte","obligatoire":true,"description":"Code de la session (6 caractères)."}],"reponse":{"statut":200,"exemple":{"session":{"code":"K7M2QX","quiz":{"id":"javascript-les-bases-k3f9a","titre":"JavaScript : les bases"},"statut":"terminee","creeLe":"2026-10-14T13:30:00.000Z","termineeLe":"2026-10-14T13:48:12.000Z","nombreParticipants":24,"nombreQuestions":10,"scoreMoyen":6120,"lienRejoindre":"https://vibe-quiz.fr/rejoindre/K7M2QX","demarreeLe":"2026-10-14T13:31:02.000Z","classement":[{"rang":1,"pseudo":"Camille","ref":"apprenant-4821","score":8740,"bonnesReponses":9,"reponses":[{"question":0,"choix":2,"correcte":true,"tempsMs":3120,"points":922}]}],"questions":[{"index":0,"enonce":"Quel mot-clé déclare une constante en JavaScript ?","choix":["var","let","const","static"],"bonneReponse":2,"nombreReponses":23,"nombreBonnesReponses":19,"tauxReussite":0.792,"repartition":[1,3,19,0]}]}}},"url":"https://vibe-quiz.fr/api/v1/sessions/{code}"}],"exempleCurl":["curl -s https://vibe-quiz.fr/api/v1/quiz -H \"Authorization: Bearer $VIBE_QUIZ_API_KEY\"","curl -s -X POST https://vibe-quiz.fr/api/v1/quiz -H \"Authorization: Bearer $VIBE_QUIZ_API_KEY\" -H \"Content-Type: application/json\" -d @quiz.json"]}