# Role menus

## `GET /api/guilds/{guild_id}/role-menus`

**List role menus**

Returns every role menu in the guild.

**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 role menus.**

Model: array of {ref}`RoleMenuSchema <model-rolemenuschema>`

Type: array of {ref}`RoleMenuSchema <model-rolemenuschema>`


## `POST /api/guilds/{guild_id}/role-menus`

**Create a role menu**

Creates a role menu with no message yet. The bot posts it, then PATCHes its message_id.

**Parameters**

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

**Request body**

Model: {ref}`RoleMenuCreate <model-rolemenucreate>`

| Field | Type | Required | Description |
|---|---|---|---|
| `channel_id` | integer | yes |  |
| `title` | string | yes |  |
| `description` | string \| null | no |  |
| `max_roles` | integer | no |  |

**Response `201` — The created role menu.**

Model: {ref}`RoleMenuSchema <model-rolemenuschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string (uuid) | yes |  |
| `guild_id` | integer | yes |  |
| `channel_id` | integer | yes |  |
| `message_id` | integer \| null | yes |  |
| `title` | string | yes |  |
| `description` | string \| null | yes |  |
| `max_roles` | integer | yes |  |
| `options` | array of {ref}`RoleMenuOptionSchema <model-rolemenuoptionschema>` | yes |  |


## `DELETE /api/guilds/{guild_id}/role-menus/{menu_id}`

**Delete a role menu**

Deletes a role menu and its options.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `menu_id` | path | string (uuid) | yes | The role menu's ID. |

**Response `204`** — The role menu was deleted.


## `GET /api/guilds/{guild_id}/role-menus/{menu_id}`

**Get a role menu**

Returns one role menu with its button options.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `menu_id` | path | string (uuid) | yes | The role menu's ID. |

**Response `200` — The role menu.**

Model: {ref}`RoleMenuSchema <model-rolemenuschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string (uuid) | yes |  |
| `guild_id` | integer | yes |  |
| `channel_id` | integer | yes |  |
| `message_id` | integer \| null | yes |  |
| `title` | string | yes |  |
| `description` | string \| null | yes |  |
| `max_roles` | integer | yes |  |
| `options` | array of {ref}`RoleMenuOptionSchema <model-rolemenuoptionschema>` | yes |  |


## `PATCH /api/guilds/{guild_id}/role-menus/{menu_id}`

**Update a role menu**

Changes only the fields present in the request body.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `menu_id` | path | string (uuid) | yes | The role menu's ID. |

**Request body**

Model: {ref}`RoleMenuUpdate <model-rolemenuupdate>`

| Field | Type | Required | Description |
|---|---|---|---|
| `channel_id` | integer \| null | no |  |
| `message_id` | integer \| null | no |  |
| `title` | string \| null | no |  |
| `description` | string \| null | no |  |
| `max_roles` | integer \| null | no |  |

**Response `200` — The updated role menu.**

Model: {ref}`RoleMenuSchema <model-rolemenuschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string (uuid) | yes |  |
| `guild_id` | integer | yes |  |
| `channel_id` | integer | yes |  |
| `message_id` | integer \| null | yes |  |
| `title` | string | yes |  |
| `description` | string \| null | yes |  |
| `max_roles` | integer | yes |  |
| `options` | array of {ref}`RoleMenuOptionSchema <model-rolemenuoptionschema>` | yes |  |


## `DELETE /api/guilds/{guild_id}/role-menus/{menu_id}/options/{role_id}`

**Remove a role menu option**

Removes the button for a Discord role from the menu. Returns the updated menu.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `menu_id` | path | string (uuid) | yes | The role menu's ID. |
| `role_id` | path | integer | yes | The Discord role ID the button grants. |

**Response `200` — The updated role menu.**

Model: {ref}`RoleMenuSchema <model-rolemenuschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string (uuid) | yes |  |
| `guild_id` | integer | yes |  |
| `channel_id` | integer | yes |  |
| `message_id` | integer \| null | yes |  |
| `title` | string | yes |  |
| `description` | string \| null | yes |  |
| `max_roles` | integer | yes |  |
| `options` | array of {ref}`RoleMenuOptionSchema <model-rolemenuoptionschema>` | yes |  |


## `PUT /api/guilds/{guild_id}/role-menus/{menu_id}/options/{role_id}`

**Add or edit a role menu option**

Adds or edits the button for a Discord role on the menu. Returns the updated menu.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `guild_id` | path | integer | yes | The Discord server ID. Only the SideQuest server works. |
| `menu_id` | path | string (uuid) | yes | The role menu's ID. |
| `role_id` | path | integer | yes | The Discord role ID the button grants. |

**Request body**

Model: {ref}`RoleMenuOptionUpsert <model-rolemenuoptionupsert>`

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string | yes |  |
| `emoji` | string \| null | no |  |
| `description` | string \| null | no |  |
| `position` | integer \| null | no |  |

**Response `200` — The updated role menu.**

Model: {ref}`RoleMenuSchema <model-rolemenuschema>`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string (uuid) | yes |  |
| `guild_id` | integer | yes |  |
| `channel_id` | integer | yes |  |
| `message_id` | integer \| null | yes |  |
| `title` | string | yes |  |
| `description` | string \| null | yes |  |
| `max_roles` | integer | yes |  |
| `options` | array of {ref}`RoleMenuOptionSchema <model-rolemenuoptionschema>` | yes |  |