kaboot/docs/API.md

Kaboot Backend API Documentation

The Kaboot backend provides a RESTful API for managing quizzes and user profiles.

Base URL

The backend server runs at: http://localhost:3001

Authentication

All routes under /api/* require authentication using an OIDC Bearer token in the Authorization header.

Authorization: Bearer <your_access_token>

Tokens are issued by the Authentik Identity Provider.

---

Endpoints

Health Check

GET /health

Check the operational status of the backend server.

• Authentication: None
• Response: 200 OK
• Example Response:

  {
    "status": "ok",
    "timestamp": "2026-01-13T10:00:00.000Z"
  }
  

• Curl Example:

  curl http://localhost:3001/health
  

---

User Profile

GET /api/users/me

Retrieve the profile of the currently authenticated user.

• Authentication: Required
• Response: 200 OK
• Example Response:

  {
    "id": "user_123",
    "username": "jdoe",
    "email": "jdoe@example.com",
    "displayName": "John Doe",
    "createdAt": "2026-01-13T10:00:00.000Z",
    "lastLogin": "2026-01-13T10:00:00.000Z",
    "isNew": false
  }
  

• Curl Example:

  curl -H "Authorization: Bearer <token>" http://localhost:3001/api/users/me
  

---

Quizzes

GET /api/quizzes

List all quizzes created by the authenticated user.

• Authentication: Required
• Response: 200 OK
• Example Response:

  [
    {
      "id": "quiz_8b3f...",
      "title": "World Capitals",
      "source": "manual",
      "aiTopic": null,
      "createdAt": "2026-01-13T10:00:00.000Z",
      "updatedAt": "2026-01-13T10:00:00.000Z",
      "questionCount": 5
    }
  ]
  

• Curl Example:

  curl -H "Authorization: Bearer <token>" http://localhost:3001/api/quizzes
  

GET /api/quizzes/:id

Retrieve full details for a specific quiz, including all questions and answer options.

• Authentication: Required
• Response: 200 OK or 404 Not Found
• Example Response:

  {
    "id": "quiz_8b3f...",
    "title": "World Capitals",
    "source": "manual",
    "aiTopic": null,
    "createdAt": "2026-01-13T10:00:00.000Z",
    "updatedAt": "2026-01-13T10:00:00.000Z",
    "questions": [
      {
        "id": "question_456",
        "text": "What is the capital of Japan?",
        "timeLimit": 20,
        "orderIndex": 0,
        "options": [
          {
            "id": "option_789",
            "text": "Tokyo",
            "isCorrect": true,
            "shape": "triangle",
            "color": "red",
            "reason": "Tokyo is the political and economic center of Japan.",
            "orderIndex": 0
          }
        ]
      }
    ]
  }
  

• Curl Example:

  curl -H "Authorization: Bearer <token>" http://localhost:3001/api/quizzes/quiz_8b3f...
  

POST /api/quizzes

Create a new quiz.

• Authentication: Required
• Validation Rules:
  • title: Required, non-empty string.
  • source: Required, must be 'manual' or 'ai_generated'.
  • questions: Required, array with at least 1 question.
  • Question validation:
    • text: Required, non-empty string.
    • options: Required, array with at least 2 options.
    • Each option:
      • text: Required, non-empty string.
      • isCorrect: Required, boolean.
      • shape: Required, one of 'triangle', 'diamond', 'circle', 'square'.
      • color: Required, one of 'red', 'blue', 'yellow', 'green'.
      • reason: Optional, string explaining the answer.
    • At least one option must be marked as correct (isCorrect: true).
• Request Body:

  {
    "title": "Space Exploration",
    "source": "manual",
    "questions": [
      {
        "text": "Which planet is known as the Red Planet?",
        "timeLimit": 20,
        "options": [
          { "text": "Mars", "isCorrect": true, "shape": "triangle", "color": "red" },
          { "text": "Venus", "isCorrect": false, "shape": "diamond", "color": "blue" }
        ]
      }
    ]
  }
  

• Response: 201 Created
• Example Response:

  {
    "id": "new_quiz_uuid"
  }
  

• Curl Example:

  curl -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
    -d '{"title":"Space Quiz","source":"manual","questions":[{"text":"Which planet is known as the Red Planet?","options":[{"text":"Mars","isCorrect":true,"shape":"triangle","color":"red"},{"text":"Venus","isCorrect":false,"shape":"diamond","color":"blue"}]}]}' \
    http://localhost:3001/api/quizzes
  

PUT /api/quizzes/:id

Update an existing quiz. This operation replaces the existing questions and options.

• Authentication: Required
• Validation Rules: Same as POST /api/quizzes.
• Response: 200 OK or 404 Not Found
• Curl Example:

  curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
    -d '{"title":"Updated Space Quiz","questions":[{"text":"Which planet is red?","options":[{"text":"Mars","isCorrect":true,"shape":"triangle","color":"red"},{"text":"Venus","isCorrect":false,"shape":"diamond","color":"blue"}]}]}' \
    http://localhost:3001/api/quizzes/quiz_uuid
  

DELETE /api/quizzes/:id

Permanently delete a quiz.

• Authentication: Required
• Response: 204 No Content or 404 Not Found
• Curl Example:

  curl -X DELETE -H "Authorization: Bearer <token>" http://localhost:3001/api/quizzes/quiz_uuid
  

---

Error Responses

The API returns standard HTTP status codes along with a JSON error object.

• 400 Bad Request Returned when the request body is invalid or validation fails.

  { "error": "Title is required and cannot be empty" }
  

• 401 Unauthorized Returned when the Bearer token is missing, expired, or invalid.

  { "error": "Missing or invalid authorization header" }
  

  or

  { "error": "Invalid token", "details": "..." }
  

• 404 Not Found Returned when the requested quiz does not exist or does not belong to the user.

  { "error": "Quiz not found" }
  

• 500 Internal Server Error Returned when an unexpected error occurs on the server.

  { "error": "Internal server error" }