Quiz Battles

Live multiplayer quiz showdowns between users (or bot fallbacks) powered by WebSocket matchmaking.

Join Online Matchmaking Queue

Enters the live matchmaking queue for a 1v1 quiz battle.

Endpoint

POST /api/v2/quiz-battles/queue/join

Headers

Authorization: Bearer <jwt_access_token>

Request Body

Field	Type	Required	Description
`topicId`	`string`	No	Specific topic or course UUID (omit for random)
`stakeAmount`	`number`	No	Gem wager amount (e.g. 50 gems)

{
  "topicId": "topic-uuid-1",
  "stakeAmount": 50
}

Response (200 OK)

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "queueTicket": "ticket-9812",
    "matchmakingTimeoutSeconds": 30
  },
  "message": "Searching for opponent..."
}

Start Bot Battle (Fallback / Solo Play)

Instantly starts a simulated 1v1 battle against an AI bot when no live players are available.

Endpoint

POST /api/v2/quiz-battles/bot/start

Response (200 OK)

{
  "success": true,
  "data": {
    "roomId": "room-bot-9821",
    "opponent": {
      "username": "CodeMasterBot",
      "avatarUrl": "https://ik.imagekit.io/learnway/bots/bot1.png"
    },
    "questions": [ ... ]
  }
}