Documentation de l’API

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.

La même description, complète et lisible par une IA, est disponible en JSON sur https://vibe-quiz.fr/api/v1. Donnez cette adresse à Claude Code : il y trouvera tout ce qu’il faut.

Principe

Il n’y a pas d’éditeur de quiz dans l’interface : les quiz se créent et se modifient uniquement par cette API, en pratique par Claude Code. L’interface sert à lancer une session, à la projeter et à consulter les résultats.

URL de base : https://vibe-quiz.fr/api/v1. Corps et réponses en JSON, dates en ISO 8601 (UTC).

Authentification

Chaque requête porte l’en-tête Authorization: Bearer <votre clé>. Créez votre clé sur la page Clés API de votre espace : elle n’est affichée qu’une fois. 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é.

Limite : 60 requêtes par minute et par clé. Réponse 429 avec l’en-tête `Retry-After` (en secondes).

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

Format d’un quiz

Champ	Règle
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
questions[].type	"qcm" (facultatif, seule valeur disponible pour l’instant ; sondages, nuages de mots et échelles arriveront plus tard)
questions[].enonce	texte, obligatoire, 300 caractères maximum
questions[].choix	liste de 2 à 4 textes distincts, 120 caractères maximum chacun
questions[].bonneReponse	entier, obligatoire : index de la bonne réponse dans `choix`, en comptant à partir de 0. Une seule bonne réponse par question.
questions[].duree	entier, facultatif : temps de réponse en secondes, de 5 à 120 (20 par défaut)
questions[].explication	texte ou null, facultatif, 500 caractères maximum : affichée à l’écran au moment de la révélation

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.

Actions

GET/api/v1/quiz

Lister vos quiz, du plus récemment modifié au plus ancien.

limite paramètre d’URL (facultatif) Nombre maximum de quiz (1 à 200, 100 par défaut).

Réponse 200

{
  "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"
    }
  ]
}

POST/api/v1/quiz

Créer un quiz.

Le quiz est prêt immédiatement dans le tableau de bord du formateur. L’`id` renvoyé sert à toutes les autres actions.

Corps de la requête

{
  "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."
    }
  ]
}

Réponse 201

{
  "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."
      }
    ]
  }
}

GET/api/v1/quiz/{id}

Lire un quiz complet, avec ses questions et les bonnes réponses.

id dans le chemin Identifiant du quiz (champ `id`).

Réponse 200

{
  "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."
      }
    ]
  }
}

PUT/api/v1/quiz/{id}

Remplacer entièrement un quiz (titre, description et toutes les questions).

Même corps que la création. Les sessions déjà jouées gardent leurs questions d’origine.

id dans le chemin Identifiant du quiz.

Corps de la requête

{
  "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."
    }
  ]
}

Réponse 200

{
  "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."
      }
    ]
  }
}

PATCH/api/v1/quiz/{id}

Modifier partiellement un quiz.

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.

id dans le chemin Identifiant du quiz.

Corps de la requête

{
  "titre": "JavaScript : les fondamentaux"
}

Réponse 200

{
  "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."
      }
    ]
  }
}

DELETE/api/v1/quiz/{id}

Supprimer un quiz.

Les résultats des sessions déjà jouées sont conservés.

id dans le chemin Identifiant du quiz.

Réponse 200

{
  "supprime": true
}

POST/api/v1/quiz/{id}/dupliquer

Dupliquer un quiz (la copie s’appelle « … (copie) »).

id dans le chemin Identifiant du quiz à copier.

Réponse 201

{
  "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."
      }
    ]
  }
}

GET/api/v1/sessions

Lister vos sessions (parties jouées ou en cours), de la plus récente à la plus ancienne.

quiz paramètre d’URL (facultatif) Ne garder que les sessions de ce quiz (son `id`).
depuis paramètre d’URL (facultatif) Sessions créées à partir de cette date (ex. 2026-10-01).
jusqua paramètre d’URL (facultatif) Sessions créées jusqu’à cette date incluse.
limite paramètre d’URL (facultatif) Nombre maximum de sessions (1 à 200, 50 par défaut).

Réponse 200

{
  "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"
    }
  ]
}

GET/api/v1/sessions/{code}

Lire une session et ses résultats : classement final, score par participant et par question.

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

code dans le chemin Code de la session (6 caractères).

Réponse 200

{
  "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
        ]
      }
    ]
  }
}

Lien partenaire (ref)

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

https://vibe-quiz.fr/rejoindre/{code}?ref={identifiant-apprenant}

# Exemple
https://vibe-quiz.fr/rejoindre/K7M2QX?ref=apprenant-4821

Une session se lance depuis l’interface (bouton « Lancer une session »), pas depuis l’API. 6 caractères, sans caractères ambigus (pas de 0/O, 1/I/L). Une session expire 24 heures après sa création. 50 participants maximum par session.

Règle du score

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.

Erreurs

Les erreurs sont en français et désignent le champ fautif avec la correction attendue : c’est ce qui permet à Claude de corriger sa requête tout seul.

{
  "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."
      }
    ]
  }
}

Statut	Code	Signification
400	validation	Données invalides : `details` liste chaque champ fautif et la correction attendue.
400	json_invalide	Le corps de la requête n’est pas du JSON valide.
401	non_authentifie	Clé absente, invalide ou révoquée.
404	introuvable	Quiz ou session inexistant dans votre compte.
405	methode_non_autorisee	Méthode HTTP non prise en charge sur ce chemin.
409	conflit	Action impossible dans l’état actuel.
429	trop_de_requetes	Plus de 60 requêtes par minute : attendez le délai indiqué par `Retry-After`.
500	erreur_serveur	Erreur inattendue : réessayez, puis signalez-la si elle persiste.