A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Guild members
description: Guild member objects, profiles, voice moderation, ownership, removal and roles.
---
import RouteHeader from '@/components/RouteHeader.astro';
A guild member is an account that has joined a guild, with a nickname, avatar, roles and moderation state that apply in that guild only.
Every route here needs membership of the guild, and a target that isn't a member returns 404 `UNKNOWN_MEMBER`.
## Guild member object
### Structure
| Field | Type | Description |
| --- | --- | --- |
| user | [partial user](/http-api/users/#partial-user-object) object | The account the membership belongs to |
| nick | ?string | The nickname in this guild |
| avatar<sup>1</sup> | ?string | The image hash of the guild avatar |
| banner<sup>1</sup> | ?string | The image hash of the guild banner |
| accent_color | ?integer | The guild profile accent color as packed 24-bit RGB |
| roles<sup>2</sup> | array[snowflake] | The IDs of the member's roles (max 250) |
| joined_at | ISO8601 timestamp | The time the account joined this guild |
| mute<sup>3</sup> | boolean | Whether the member is muted in voice |
| deaf | boolean | Whether the member is deafened in voice |
| communication_disabled_until<sup>4</sup> | ?ISO8601 timestamp | The time the communication timeout ends |
| profile_flags?<sup>5</sup> | integer | The [guild member profile flags](#guild-member-profile-flags) set on the membership |
| mention_flags?<sup>5</sup> | integer | The [reply mention preference](/http-api/users/#reply-mention-preferences) for this guild |
<sup>1</sup> An animated hash starts with `a_`
<sup>2</sup> The everyone role is never listed
<sup>3</sup> True for a moderator mute and while a communication timeout is active
<sup>4</sup> The time can be in the past, and the [communication timeout](/http-api/permissions/#communication-timeout) is only active while it's in the future
<sup>5</sup> Omitted when the value is 0
### Example
```json
{
"user": {"id": "1489002177550843906", "username": "ada", "discriminator": "0042"},
"nick": "Ada L.",
"avatar": null,
"banner": null,
"accent_color": 3447003,
"roles": ["1489002177550843910"],
"joined_at": "2026-08-14T09:12:44.000Z",
"mute": false,
"deaf": false,
"communication_disabled_until": null
}
```
## Guild member profile flags
A set flag makes the member show the default avatar or banner in this guild in place of their account one.
| Value | Name | Description |
| --- | --- | --- |
| 1 << 0 | AVATAR_UNSET | Show the default avatar |
| 1 << 1 | BANNER_UNSET | Show the default banner |
## Guild member update object
The request body for [Modify current guild member](#modify-current-guild-member) and [Modify guild member](#modify-guild-member). An omitted field keeps its value.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| nick?<sup>1</sup> | ?string | The nickname (1-32 characters) |
| roles?<sup>2</sup> | array[snowflake] | The complete replacement role set (max 250) |
| avatar?<sup>3</sup> | ?base64 string | The guild avatar image data, or null to clear it |
| banner?<sup>3</sup> | ?base64 string | The guild banner image data, or null to clear it |
| bio? | ?string | The guild profile biography (1-320 characters) |
| pronouns? | ?string | The guild profile pronouns (1-40 characters) |
| accent_color? | ?integer | The guild profile accent color as packed 24-bit RGB (0-16777215) |
| profile_flags? | ?integer | The [guild member profile flags](#guild-member-profile-flags) to store |
| mention_flags?<sup>4</sup> | ?integer | The [reply mention preference](/http-api/users/#reply-mention-preferences) for this guild |
| mute? | boolean | Whether the member is muted in voice |
| deaf? | boolean | Whether the member is deafened in voice |
| communication_disabled_until?<sup>5</sup> | ?ISO8601 timestamp | The time the communication timeout ends |
| timeout_reason? | ?string | The reason for the timeout (1-512 characters) |
| channel_id?<sup>6</sup> | ?snowflake | The voice channel to move the member into, or null to disconnect them |
| connection_id?<sup>6</sup> | ?string | The voice connection to move, defaulting to all of them (1-32 characters) |
<sup>1</sup> A blank string clears the nickname
<sup>2</sup> Roles missing from the array are removed, and unknown role IDs are dropped
<sup>3</sup> Base64 image data with an optional data URL prefix. The decoded size is limited by `avatar_max_size` in the [instance limits](/http-api/instance/#limit-keys)
<sup>4</sup> 0 restores the account-level preference
<sup>5</sup> Null or a past time clears the timeout, and a time more than 365.25 days ahead returns `TIMEOUT_CANNOT_EXCEED_365_DAYS`
<sup>6</sup> A `connection_id` that isn't one of the member's connections returns 400 `USER_NOT_IN_VOICE`
## List guild members
<RouteHeader method="GET" path="/v1/guilds/{guild_id}/members" bot />
Returns [guild member objects](#guild-member-object) in ascending user ID order. It needs no permission.
### Query parameters
| Field | Type | Description |
| --- | --- | --- |
| limit? | integer | The maximum number of members to return (1-1000, default 1) |
| after? | snowflake | Only return members with a user ID greater than this |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[guild member](#guild-member-object) object] | Members were returned |
The rate limit is 40 requests per 10 seconds, on the `guild:members::guild_id` bucket.
## Get current guild member
<RouteHeader method="GET" path="/v1/guilds/{guild_id}/members/@me" bot />
Returns your own [guild member object](#guild-member-object).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild member](#guild-member-object) object | The membership was returned |
The rate limit is 40 requests per 10 seconds, on the `guild:members::guild_id` bucket.
## Get guild member
<RouteHeader method="GET" path="/v1/guilds/{guild_id}/members/{user_id}" bot />
Returns one member's [guild member object](#guild-member-object).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild member](#guild-member-object) object | The membership was returned |
The rate limit is 40 requests per 10 seconds, on the `guild:members::guild_id` bucket.
## Modify current guild member
<RouteHeader method="PATCH" path="/v1/guilds/{guild_id}/members/@me" bot auditReason />
Updates your own membership and returns the [guild member object](#guild-member-object).
| Change | Permission |
| --- | --- |
| nick | [CHANGE_NICKNAME](/http-api/permissions/), and without it Fluxer ignores `nick` |
| mute | [MUTE_MEMBERS](/http-api/permissions/) |
| deaf | [DEAFEN_MEMBERS](/http-api/permissions/) |
| channel_id | [MOVE_MEMBERS](/http-api/permissions/), and [VIEW_CHANNEL](/http-api/permissions/) and [CONNECT](/http-api/permissions/) in the destination |
When `interaction_tier` is `legacy`, an [unverified account](/http-api/users/#account-tiers) can't change `nick`, `avatar`, `banner`, `bio`, `pronouns`, `accent_color` or `profile_flags`. `avatar`, `banner`, `bio` and `accent_color` are ignored without the `feature_per_guild_profiles` [limit](/http-api/instance/#limit-keys). A timed-out member can't change `nick`, and you can't time yourself out.
You can change each of `avatar`, `banner`, `bio`, `pronouns` and `accent_color` 25 times per 30 minutes in each guild. Going over returns 400 `INVALID_FORM_BODY` with a field code such as `AVATAR_CHANGED_TOO_MANY_TIMES`, and nothing is saved.
### JSON body
The body is a [guild member update object](#guild-member-update-object) without `roles`, which Fluxer ignores here.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild member](#guild-member-object) object | The membership was updated |
| 400 | [error response](/http-api/#error-response) | `USER_NOT_IN_VOICE` when `channel_id` is set and the member isn't in voice |
| 403 | [error response](/http-api/#error-response) | `MISSING_PERMISSIONS` for a missing voice permission or a timeout on yourself |
| 403 | [error response](/http-api/#error-response) | `PROFILE_EMAIL_VERIFICATION_REQUIRED`, `COMMUNICATION_DISABLED`, `CONTENT_BLOCKED` or `ACCOUNT_LIMITED` |
Fluxer sends [Guild Member Update](/gateway/events/#guild-member-update).
The rate limit is 20 requests per 10 seconds, on the `guild:member:update::guild_id` bucket.
## Modify guild member
<RouteHeader method="PATCH" path="/v1/guilds/{guild_id}/members/{user_id}" bot auditReason />
Updates another member and returns the [guild member object](#guild-member-object). Each field needs the permission below and, except for `roles`, a higher role than the target. The guild owner skips the permission and role checks.
| Change | Permission |
| --- | --- |
| nick | [MANAGE_NICKNAMES](/http-api/permissions/) |
| roles | [MANAGE_ROLES](/http-api/permissions/) and a higher role than every role added or removed |
| timeout | [MODERATE_MEMBERS](/http-api/permissions/), and the target can't have [ADMINISTRATOR](/http-api/permissions/) |
| mute | [MUTE_MEMBERS](/http-api/permissions/) |
| deaf | [DEAFEN_MEMBERS](/http-api/permissions/) |
| channel_id | [MOVE_MEMBERS](/http-api/permissions/), and [VIEW_CHANNEL](/http-api/permissions/) and [CONNECT](/http-api/permissions/) in the destination |
Fluxer ignores `avatar`, `banner`, `bio`, `pronouns`, `accent_color`, `profile_flags` and `mention_flags` here, but a blocked `bio` or `pronouns` still returns 403 `CONTENT_BLOCKED`. `MANAGE_ROLES` and `MODERATE_MEMBERS` are [elevated permissions](/http-api/permissions/#elevated-permissions).
If `user_id` is your own ID, profile fields follow [Modify current guild member](#modify-current-guild-member).
### JSON body
The body is a [guild member update object](#guild-member-update-object).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild member](#guild-member-object) object | The membership was updated |
| 400 | [error response](/http-api/#error-response) | `USER_NOT_IN_VOICE` when the target isn't in voice, or `TWO_FACTOR_REQUIRED` in an elevated-MFA guild |
| 400 | [error response](/http-api/#error-response) | `INVALID_ROLE_ID` for the everyone role, or `CHANNEL_DOES_NOT_EXIST` or `CHANNEL_MUST_BE_VOICE` for `channel_id` |
| 403 | [error response](/http-api/#error-response) | `MISSING_PERMISSIONS` for a missing permission or role check, a target with ADMINISTRATOR, or a timeout on yourself |
| 403 | [error response](/http-api/#error-response) | `CONTENT_BLOCKED` for blocked profile text |
Fluxer sends [Guild Member Update](/gateway/events/#guild-member-update). If the member joined through an [invite](/http-api/invites/#invite-object) with `temporary` set, a non-empty `roles` makes their membership permanent.
The rate limit is 20 requests per 10 seconds, on the `guild:member:update::guild_id` bucket.
## Remove guild member
<RouteHeader method="DELETE" path="/v1/guilds/{guild_id}/members/{user_id}" bot auditReason />
Removes a member from the guild. You need [KICK_MEMBERS](/http-api/permissions/), an [elevated permission](/http-api/permissions/#elevated-permissions), and a higher role than the target. Removing yourself or the owner returns 404 `UNKNOWN_MEMBER`.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The member was removed |
| 400 | [error response](/http-api/#error-response) | `TWO_FACTOR_REQUIRED` in an elevated-MFA guild |
Fluxer sends [Guild Member Remove](/gateway/events/#guild-member-remove) to the guild and [Guild Delete](/gateway/events/#guild-delete) to the removed account.
The rate limit is 20 requests per 10 seconds, on the `guild:member:remove::guild_id` bucket.
## Transfer guild ownership
<RouteHeader method="POST" path="/v1/guilds/{guild_id}/transfer-ownership" bot auditReason mfa />
Makes another member the owner and returns the [guild object](/http-api/guilds/#guild-object). Only the current owner can call it, with the [sudo verification fields](/http-api/guilds/#sudo-verification-fields) unless the owner is a bot. The previous owner keeps their roles.
### Request headers
| Field | Type | Description |
| --- | --- | --- |
| X-Fluxer-Sudo-Mode-JWT? | string | The existing sudo mode proof |
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| new_owner_id | snowflake | The ID of the member to make the new owner |
| password? | string | The current owner's password |
| mfa_method? | string | The second factor to verify, one of `totp`, `webauthn` or `email_code` |
| mfa_code? | string | The authenticator code, required when the method is `totp` (1-32 characters) |
| webauthn_response? | [WebAuthn assertion](/http-api/authentication/#webauthn-assertion) object | The assertion produced when the method is `webauthn` |
| webauthn_challenge? | string | The challenge bound to the WebAuthn assertion |
| email_code_ticket? | string | The ticket from [send a sudo email code](/http-api/users/mfa/#send-a-sudo-email-code) (1-128 characters) |
| email_code? | string | The 6-digit code from that email |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild](/http-api/guilds/#guild-object) object | Ownership was transferred |
| 400 | [error response](/http-api/#error-response) | The password or code is wrong, or `CANNOT_TRANSFER_OWNERSHIP_TO_BOT` when the target is a bot |
| 403 | [error response](/http-api/#error-response) | `SUDO_MODE_REQUIRED` with the available proofs in `methods`, or `MISSING_PERMISSIONS` when you aren't the owner |
| 403 | [error response](/http-api/#error-response) | `ACCOUNT_VERIFICATION_REQUIRED` when `interaction_tier` is `enforced` and the new owner isn't [verified](/http-api/users/#account-tiers) |
Fluxer sends [Guild Update](/gateway/events/#guild-update).
The rate limit is 20 requests per 10 seconds, on the `guild:update::guild_id` bucket.
## Add guild member role
<RouteHeader method="PUT" path="/v1/guilds/{guild_id}/members/{user_id}/roles/{role_id}" bot auditReason />
Adds one role to a member. You need [MANAGE_ROLES](/http-api/permissions/), an [elevated permission](/http-api/permissions/#elevated-permissions), and a higher role than the role you add, unless you're the guild owner.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The member has the role |
| 400 | [error response](/http-api/#error-response) | `INVALID_ROLE_ID` for the everyone role, or `TWO_FACTOR_REQUIRED` in an elevated-MFA guild |
| 403 | [error response](/http-api/#error-response) | `MISSING_PERMISSIONS` without MANAGE_ROLES or a higher role than the role |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_ROLE` when the role doesn't exist and you're the owner |
Fluxer sends [Guild Member Update](/gateway/events/#guild-member-update), and a new role makes a temporary member permanent.
The rate limit is 20 requests per 10 seconds, on the `guild:member:role:add::guild_id` bucket.
## Remove guild member role
<RouteHeader method="DELETE" path="/v1/guilds/{guild_id}/members/{user_id}/roles/{role_id}" bot auditReason />
Removes one role from a member. The rules are the same as [Add guild member role](#add-guild-member-role).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The member doesn't have the role |
| 400 | [error response](/http-api/#error-response) | `INVALID_ROLE_ID` for the everyone role, or `TWO_FACTOR_REQUIRED` in an elevated-MFA guild |
| 403 | [error response](/http-api/#error-response) | `MISSING_PERMISSIONS` without MANAGE_ROLES or a higher role than the role |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_ROLE` when the role doesn't exist and you're the owner |
Fluxer sends [Guild Member Update](/gateway/events/#guild-member-update).
The rate limit is 20 requests per 10 seconds, on the `guild:member:role:remove::guild_id` bucket.