# Leveling

## `GET /api/guilds/{guild_id}/leaderboard`

**Get the XP leaderboard**

Returns a page of the guild's XP leaderboard, highest XP first.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `limit` | query | integer | no | The maximum number of entries to return. |
| `offset` | query | integer | no | The number of leading entries to skip. |

**Response `200` — A page of leaderboard entries.**

Model: {ref}`LeaderboardPage <model-leaderboardpage>`

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | array of {ref}`LeaderboardEntry <model-leaderboardentry>` | yes |  |
| `total` | integer | yes |  |
| `limit` | integer | yes |  |
| `offset` | integer | yes |  |


## `GET /api/guilds/{guild_id}/level-roles`

**List level-role rewards**

Returns the guild's level-role rewards, lowest level first.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |

**Response `200` — The guild's level-role rewards.**

Model: array of {ref}`LevelRoleSchema <model-levelroleschema>`

Type: array of {ref}`LevelRoleSchema <model-levelroleschema>`


## `DELETE /api/guilds/{guild_id}/level-roles/{level}`

**Remove a level-role reward**

Removes the level-role reward at a level.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `level` | path | integer | yes | The level the reward is granted at. |

**Response `204`** — The reward was removed.


## `PUT /api/guilds/{guild_id}/level-roles/{level}`

**Set a level-role reward**

Grants a Discord role at a level. This replaces any existing reward for that level.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `level` | path | integer | yes | The level the reward is granted at. |

**Request body**

Model: {ref}`LevelRoleUpsert <model-levelroleupsert>`

| Field | Type | Required | Description |
|---|---|---|---|
| `role_id` | integer | yes |  |

**Response `200` — The level-role reward.**

Model: {ref}`LevelRoleSchema <model-levelroleschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `level` | integer | yes |  |
| `role_id` | integer | yes |  |


## `GET /api/guilds/{guild_id}/members/{user_id}/rank`

**Get a member's rank**

Returns a member's leaderboard standing. A member with no XP yet gets zeros instead of a 404.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `user_id` | path | integer | yes | The member's Discord user ID. |

**Response `200` — The member's rank, level, and XP.**

Model: {ref}`RankSchema <model-rankschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `user_id` | integer | yes |  |
| `rank` | integer \| null | yes |  |
| `xp` | integer | yes | The member's total XP (experience points). |
| `level` | integer | yes |  |
| `message_count` | integer | yes |  |
| `xp_into_level` | integer | yes | XP (experience points) earned since reaching the current level. |
| `xp_for_next_level` | integer | yes | XP (experience points) needed to reach the next level. |


## `POST /api/guilds/{guild_id}/members/{user_id}/xp`

**Award XP**

Awards one message's worth of XP to a member, honoring the per-member cooldown and the guild's leveling-enabled setting.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `user_id` | path | integer | yes | The member's Discord user ID. |

**Response `200` — The XP award result, with any level-role changes.**

Model: {ref}`XPAwardResult <model-xpawardresult>`

| Field | Type | Required | Description |
|---|---|---|---|
| `awarded` | boolean | yes |  |
| `amount` | integer | yes | XP (experience points) awarded by this message. |
| `xp` | integer | yes | The member's new total XP (experience points). |
| `level` | integer | yes |  |
| `previous_level` | integer | yes |  |
| `leveled_up` | boolean | yes |  |
| `earned_role_ids` | array of integer | no |  |
| `remove_role_ids` | array of integer | no |  |


## `PUT /api/guilds/{guild_id}/members/{user_id}/xp`

**Set a member's XP**

Overwrites a member's XP total. The level is recomputed from the new total.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `user_id` | path | integer | yes | The member's Discord user ID. |

**Request body**

Model: {ref}`SetXPRequest <model-setxprequest>`

| Field | Type | Required | Description |
|---|---|---|---|
| `xp` | integer | yes | The new total XP (experience points) to set. |

**Response `200` — The member's updated level and XP.**

Model: {ref}`MemberLevelSchema <model-memberlevelschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `guild_id` | integer | yes |  |
| `user_id` | integer | yes |  |
| `xp` | integer | yes | The member's total XP (experience points). |
| `level` | integer | yes |  |
| `message_count` | integer | yes |  |