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

# Contests

> Time-limited competitions, entry fees, quiz submission, and prize distribution.

# Contests

Contests are structured competitions where users compete under time limits for gem/token prize pools.

***

## Get Contests

Fetch active, upcoming, and past contests with user participation metadata.

### Endpoint

```http theme={null}
GET /api/v2/user/contests
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Query Parameters

| Parameter | Type     | Required | Description                       |
| :-------- | :------- | :------- | :-------------------------------- |
| `page`    | `number` | No       | Page number (default: 1)          |
| `limit`   | `number` | No       | Items per page (default: 10)      |
| `order`   | `string` | No       | `ASC` or `DESC` (default: `DESC`) |
| `search`  | `string` | No       | Keyword search query              |

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "contest-uuid-1",
        "title": "Summer Web3 Championship 2026",
        "description": "Test your knowledge of Solidity & Layer 2 solutions.",
        "entryFeeGems": 50,
        "prizePoolGems": 5000,
        "startsAt": "2026-08-25T10:00:00.000Z",
        "endsAt": "2026-08-25T18:00:00.000Z",
        "participantCount": 142,
        "userStatus": {
          "hasJoined": true,
          "hasStarted": false,
          "hasCompleted": false,
          "score": null,
          "rank": null
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10
  }
}
```

***

## Join Contest

Enrolls the user into the contest, deducting entry fees if applicable.

### Endpoint

```http theme={null}
POST /api/v2/user/contests/:id/join
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "message": "Successfully joined contest"
}
```

***

## Submit Contest Quiz

Submits user answers upon completing the contest questions.

### Endpoint

```http theme={null}
POST /api/v2/user/contests/:id/submit
```

### Request Body

```json theme={null}
{
  "answers": [
    { "questionId": "q-101", "selectedOption": 2 },
    { "questionId": "q-102", "selectedOption": 0 }
  ],
  "timeTakenSeconds": 185
}
```