> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quiz Battles

> Real-time 1v1 PvP quiz battles with matchmaking, bot fallbacks, and gem stakes.

# 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

```http theme={null}
POST /api/v2/quiz-battles/queue/join
```

### Headers

```http theme={null}
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)                 |

```json theme={null}
{
  "topicId": "topic-uuid-1",
  "stakeAmount": 50
}
```

### Response (200 OK)

```json theme={null}
{
  "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

```http theme={null}
POST /api/v2/quiz-battles/bot/start
```

### Response (200 OK)

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