Guild members

A guild member is an account that has joined a guild. The membership has a nickname, avatar, role set, and moderation state that apply in that guild alone. Indexed member queries live on Guild member search, and bans on Guild moderation.

An unknown guild returns 404 UNKNOWN_GUILD, a non-member receives 403 MISSING_PERMISSIONS, and a guild marked unavailable returns 403 MISSING_ACCESS. Transfer guild ownership also returns 403 ACCESS_DENIED when the guild exists in storage but the Gateway reports it as not found.

The modify operations return the resulting membership, Transfer guild ownership returns the updated guild, and every other mutation returns 204 with an empty body.

A missing target returns 404

A request whose target is not a member returns 404 UNKNOWN_MEMBER whether or not the caller can see the guild. The rule covers the modify operations, Remove guild member, Add guild member role, and Remove guild member role.

Guild member object

Every field except user describes state that belongs to the membership.

Structure

Field	Type	Description
user	partial user object	The account the membership belongs to
nick	?string	The nickname the account uses in this guild, or null when none is set
avatar1	?string	The image hash of the guild-specific avatar, or null when none is set
banner1	?string	The image hash of the guild-specific banner, or null when none is set
accent_color	?integer	The guild profile accent colour as packed 24-bit RGB, or null when none is set
roles2	array[snowflake]	The IDs of the roles assigned to the membership (max 250)
joined_at	ISO8601 timestamp	The time the account became a member of this guild
mute3	boolean	Whether a moderator has muted the member in voice
deaf4	boolean	Whether a moderator has deafened the member in voice
communication_disabled_until5	?ISO8601 timestamp	The time the communication timeout expires, or null when the member is not timed out
profile_flags?6	integer	The guild member profile flags set on the membership
mention_flags?6	integer	The reply mention preference that applies only inside this guild

¹ An animated hash has the a_ prefix. Both are reported as null while the membership is marked premium sanitised

² The everyone role is never present

³ True while a moderator mute is stored on the membership and also while a communication timeout is active

⁴ True while a moderator deafen is stored on the membership. A communication timeout does not affect it

⁵ A timestamp in the past is retained until a later update supplies communication_disabled_until

⁶ Omitted while the stored value is 0, so absence means no flag is set and, for mention_flags, that the account-level preference applies

FiveCord marks a membership premium sanitised after its account loses premium, when the membership has a guild avatar, banner, bio, or accent colour. A premium sanitised membership reports avatar and banner as null.

A client compares communication_disabled_until against the current time, because a non-null value can name a moment that has already passed. A communication timeout does not reduce the member’s computed permission mask.

Example

{
  "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
}

List and direct reads can briefly differ

Get current guild member, Get guild member, and both modify operations recompute mute against the current time. In List guild members an expired timeout can leave mute true until that membership next changes.

Guild member profile flags

A guild profile asset has these states. A membership with no flag and no stored hash inherits the account-level asset. A stored hash sets a guild-specific asset. Each flag below blocks inheritance, so the client shows the default asset.

Value	Name	Description
1 << 0	AVATAR_UNSET	The guild avatar is explicitly unset, so the account avatar is not inherited
1 << 1	BANNER_UNSET	The guild banner is explicitly unset, so the account banner is not inherited

The field is validated as an integer between 0 and 2147483647, so an undefined bit below bit 31 is stored and returned unchanged. Bit 31, and any value above 2147483647, are rejected.

Guild member update object

The request body shared by Modify current guild member and Modify guild member. An omitted field preserves its current value.

Structure

Field	Type	Description
nick?1	?string	The nickname to set in this guild (1-32 characters)
roles?2	array[snowflake]	The complete replacement role set (max 250)
avatar?3	?base64 string	The guild avatar image data, or null to clear it
banner?3	?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 colour as packed 24-bit RGB (0-16777215)
profile_flags?	?integer	The guild member profile flags to store
mention_flags?4	?integer	The reply mention preference to apply in this guild
mute?5	boolean	Whether the member is muted by a moderator in voice
deaf?5	boolean	Whether the member is deafened by a moderator in voice
communication_disabled_until?6	?ISO8601 timestamp	The time at which the communication timeout expires
timeout_reason?7	?string	The reason recorded alongside the timeout (1-512 characters)
channel_id?8	?snowflake	The voice channel to move the member into, or null to disconnect them
connection_id?8	?string	The single voice connection to move, defaulting to every connection (1-32 characters)

¹ A blank string is normalised to null before the length bound runs, so an empty value clears the nickname

² A role ID absent from the supplied array is removed from the member

³ Base64 image data with an optional data URL prefix, which is not counted

⁴ One of the reply mention preference enum values, where 0 restores the account-level preference

⁵ Stored on the membership, so it applies whether or not the member holds a voice connection

⁶ An ISO 8601 date and time. A blank string is normalised to null

⁷ Trimmed, and used as the audit log reason of the member update entry when the request sends no X-Audit-Log-Reason header

⁸ channel_id moves or disconnects, and connection_id selects one of the member’s voice connections

A roles entry that does not resolve to an existing role of the guild is dropped from the replacement, so a request naming only unknown roles clears the member’s role set.

An avatar or banner base64 payload longer than 13981016 characters returns BASE64_LENGTH_INVALID, and a malformed one returns INVALID_BASE64_FORMAT. FiveCord then checks the decoded bytes against the instance-configured avatar_max_size limit, whose stock value is 10485760. The same limit applies to both fields. The decoded image must also be in a format the field accepts, and an animated AVIF is rejected. Pixel dimensions are not enforced. A value that is too large returns IMAGE_SIZE_EXCEEDS_LIMIT, and one whose format or animation is not allowed returns INVALID_IMAGE_FORMAT.

Null and any communication_disabled_until that is not in the future both clear the timeout. A time more than 365.25 days ahead returns TIMEOUT_CANNOT_EXCEED_365_DAYS, and a value that passes the schema but is not a real instant returns INVALID_TIMEOUT_VALUE. timeout_reason has no effect unless communication_disabled_until is also supplied.

Omitting connection_id applies the move or the disconnect to every voice connection the member holds in the guild. A connection_id that is not one of the member’s own connections returns 400 USER_NOT_IN_VOICE.

List guild members

GET/v1/guilds/{guild_id}/membersBot

Returns a page of guild member objects in ascending user ID order. Requires membership of the guild and no permission.

This route checks no permission bit, including VIEW_CHANNEL_MEMBERS.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Query parameters

Field	Type	Description
limit?1	integer	The maximum number of members to return (1-1000, default 1)
after?2	snowflake	The lower bound on user ID, returning only members strictly greater than this value

¹ A caller that wants a batch states limit explicitly, because the default returns one member

² The cursor is exclusive, and there is no descending or before form

Response

Status	Body	Condition
200	array[guild member object]	Members were returned
403	error response	Guild is unavailable, or the caller is not a member
404	error response	Guild does not exist and the request returns UNKNOWN_GUILD

Rate limit

40 requests per 10 seconds for each authenticated user and guild ID, on the guild:members::guild_id bucket.

Get current guild member

GET/v1/guilds/{guild_id}/members/@meBot

Returns the authenticated account’s own guild member object. Requires membership of the guild and no permission.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response

Status	Body	Condition
200	guild member object	Membership was returned
403	error response	Guild is unavailable, or the caller is not a member
4041	error response	Guild does not exist, or the membership record is absent

¹ A missing guild returns UNKNOWN_GUILD and a missing membership record returns UNKNOWN_MEMBER

Rate limit

40 requests per 10 seconds for each authenticated user and guild ID, on the shared guild:members::guild_id bucket.

Get guild member

GET/v1/guilds/{guild_id}/members/{user_id}Bot

Returns one member’s guild member object. Requires membership of the guild and no permission.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The ID of the target member

Response

Status	Body	Condition
200	guild member object	Membership was returned
403	error response	Guild is unavailable, or the caller is not a member
404	error response	Guild does not exist, returning UNKNOWN_GUILD, or the target is not a member, returning UNKNOWN_MEMBER

Rate limit

40 requests per 10 seconds for each authenticated user and guild ID, on the shared guild:members::guild_id bucket.

Modify current guild member

PATCH/v1/guilds/{guild_id}/members/@meBotAudit reason

Modifies the authenticated account’s own membership and returns the resulting guild member object. Requires membership of the guild. Emits a Guild Member Update Gateway event.

Limitations

• Changing the nickname requires CHANGE_NICKNAME.
• Supplying channel_id requires MOVE_MEMBERS, even for the caller’s own membership.
• Supplying mute requires MUTE_MEMBERS, and deaf requires DEAFEN_MEMBERS.
• Supplying nick, avatar, banner, bio, pronouns, accent_color, or profile_flags requires a verified email address, and a bot account is exempt. An unverified account is rejected with 403 PROFILE_EMAIL_VERIFICATION_REQUIRED.

A caller without CHANGE_NICKNAME does not fail the request. FiveCord discards the nickname change and applies every other supplied field. A member who holds the permission but is timed out is rejected with 403 COMMUNICATION_DISABLED.

A blocked nick, bio or pronouns returns 403 CONTENT_BLOCKED.

Guild avatar, banner, biography, and accent colour also require the instance-configured feature_per_guild_profiles limit for the calling account. FiveCord discards any of those fields supplied without that capability and applies every other field. Pronouns, profile_flags, and mention_flags do not require it.

A channel_id destination must be a guild voice channel, and the caller must hold both VIEW_CHANNEL and CONNECT there. Supplying channel_id for a member with no live voice connection returns 400 USER_NOT_IN_VOICE. Supplying mute or deaf for such a member succeeds, stores the flags, and emits no voice Dispatch.

FiveCord rejects a supplied communication_disabled_until with 403 MISSING_PERMISSIONS before any other timeout check. Modify guild member addressed at the caller’s own user ID is rejected the same way.

A profile change limit fails the whole request

Avatar, banner, biography, pronouns, and accent colour each have a limit of 25 changes per 30 minutes for each authenticated user and guild. Exhausting one returns 400 INVALID_FORM_BODY and applies no field at all.

Avatar and banner consume their limit whenever the field is present. Biography, pronouns, and accent colour consume theirs only when the supplied value differs from the stored one. The field code is AVATAR_CHANGED_TOO_MANY_TIMES, BANNER_CHANGED_TOO_MANY_TIMES, BIO_CHANGED_TOO_MANY_TIMES, PRONOUNS_CHANGED_TOO_MANY_TIMES, or ACCENT_COLOR_CHANGED_TOO_MANY_TIMES.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

The body is a guild member update object without roles. A supplied roles field is discarded without an error, so role assignment goes through Modify guild member.

Response

Status	Body	Condition
200	guild member object	Membership was processed
400	error response	Image data or a profile change limit rejects the request
400	error response	channel_id was supplied for a member with no live voice connection
400	error response	Destination channel does not exist or is not a voice channel
403	error response	Guild is unavailable, the caller is not a member, or the email address is unverified
403	error response	Blocked content was supplied, the caller is timed out, or a required voice permission is absent
403	error response	communication_disabled_until was supplied
404	error response	Guild does not exist, or the membership record or account is absent

Side effects

The operation updates the membership, records a MEMBER_UPDATE audit entry and emits Guild Member Update.

The target’s own sessions always receive the Dispatch. Other guild sessions receive it subject to event filtering. The Dispatch is produced even when the resulting membership is unchanged, and an update that changes nothing records no audit entry.

Supplying channel_id moves or disconnects every voice connection the member holds, or only the one named by connection_id. It records one MEMBER_MOVE or MEMBER_DISCONNECT audit entry for the whole request, however many connections it touched. A move into the channel the member already occupies records no entry. It emits Voice State Update to sessions that can view the affected channel. Supplying mute or deaf updates the membership, records no separate audit entry, and emits the same voice Dispatch once for each live connection.

FiveCord emits Guild Audit Log Entry Create for every audit entry. A request that fails after uploading a new avatar or banner leaves the previous asset in place.

Rate limit

20 requests per 10 seconds for each authenticated user and guild ID, on the guild:member:update::guild_id bucket.

Modify guild member

PATCH/v1/guilds/{guild_id}/members/{user_id}BotAudit reason

Modifies another member’s guild state and returns the resulting guild member object. Requires membership of the guild. Emits a Guild Member Update Gateway event.

Limitations

• Changing another member’s nickname requires MANAGE_NICKNAMES and role hierarchy authority over the target.
• Replacing roles requires MANAGE_ROLES and hierarchy authority over every role the replacement adds or removes, and the guild owner bypasses both checks.
• Applying communication_disabled_until requires MODERATE_MEMBERS and hierarchy authority, and the target must not hold ADMINISTRATOR.
• Applying mute requires MUTE_MEMBERS, applying deaf requires DEAFEN_MEMBERS, and both require hierarchy authority over the target.
• Moving the target requires MOVE_MEMBERS and hierarchy authority, plus VIEW_CHANNEL and CONNECT for the caller in the destination.

A blocked nick returns 403 CONTENT_BLOCKED.

Hierarchy authority over the target is not checked for roles, so a caller who outranks every affected role can replace the role set of a member who outranks them. The everyone role in the array is rejected with the field code INVALID_ROLE_ID.

FiveCord never checks the target’s own permissions in the destination, so a member can be moved into a channel they could not join themselves. Disconnecting sets channel_id to null and requires the same permission.

Supplying channel_id for a target with no live voice connection, or a connection_id that is not one of the target’s own, returns 400 USER_NOT_IN_VOICE. Supplying mute or deaf for such a target succeeds and stores the flags. A destination that does not exist returns the field code CHANNEL_DOES_NOT_EXIST, and one that is not a voice channel CHANNEL_MUST_BE_VOICE.

MANAGE_ROLES and MODERATE_MEMBERS are elevated permissions. When the guild MFA level is elevated, a caller who is not the guild owner also needs an enrolled multi-factor authenticator to replace roles or apply communication_disabled_until.

A caller addressing their own user ID here follows the self-targeted rules of Modify current guild member for the guild profile fields. The body remains the complete update object, so roles is accepted. Replacing their own role set still requires MANAGE_ROLES and hierarchy authority, and communication_disabled_until is still rejected with 403 MISSING_PERMISSIONS.

Guild profile fields belong to their own account

avatar, banner, bio, pronouns, accent_color, profile_flags, and mention_flags describe the target’s own profile, so a moderator cannot set them. Supplying one for another member leaves it unwritten, and the request still applies every field the caller may set.

A blocklisted bio or pronouns returns 403

A request that supplies a blocked bio or pronouns for another member fails with CONTENT_BLOCKED, even though FiveCord never writes those fields for another member.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The ID of the target member

JSON body

The body is a guild member update object.

Response

Status	Body	Condition
200	guild member object	Membership was processed
400	error response	Role set or timeout value rejects the request
4001	error response	Caller holds MANAGE_ROLES or MODERATE_MEMBERS without an enrolled authenticator in an elevated-MFA guild
400	error response	channel_id was supplied for a target with no live voice connection
400	error response	Destination channel does not exist or is not a voice channel
403	error response	Guild is unavailable, the caller is not a member, or a required permission is absent
403	error response	Blocked content was supplied, hierarchy authority is absent, or the target holds ADMINISTRATOR
403	error response	Target is the caller and communication_disabled_until was supplied
404	error response	Guild does not exist, returning UNKNOWN_GUILD, or the target membership or account is absent, returning UNKNOWN_MEMBER

¹ The missing-authenticator error code is TWO_FACTOR_REQUIRED, returned only after the permission itself has been confirmed, so a caller lacking the permission entirely receives 403 instead

Side effects

The operation has the same effects as Modify current guild member. Applying a non-empty role set also makes a temporary membership permanent. A membership is temporary when the member joined through an invite whose temporary field is true.

Rate limit

20 requests per 10 seconds for each authenticated user and guild ID, on the guild:member:update::guild_id bucket.

Remove guild member

DELETE/v1/guilds/{guild_id}/members/{user_id}BotAudit reason

Removes a member from the guild and returns 204 with an empty body. Requires membership, KICK_MEMBERS, and role hierarchy authority over the target. Emits a Guild Member Remove Gateway event.

KICK_MEMBERS is an elevated permission, so a caller who is not the guild owner needs an enrolled multi-factor authenticator while the guild MFA level is elevated.

The caller and the guild owner cannot be removed through this operation, and both are reported as 404 UNKNOWN_MEMBER.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The ID of the target member

Response

Status	Body	Condition
204	empty	Member was removed
4001	error response	Caller holds KICK_MEMBERS without an enrolled authenticator in an elevated-MFA guild
403	error response	Guild is unavailable, the caller is not a member, or KICK_MEMBERS is absent
403	error response	Hierarchy authority over the target is absent
404	error response	Guild does not exist, returning UNKNOWN_GUILD
404	error response	Target is not a member, is the caller, or is the guild owner, each returning UNKNOWN_MEMBER

¹ The error code is TWO_FACTOR_REQUIRED, returned only after the permission itself has been confirmed

Side effects

Rejoining within one year resumes any communication timeout that has not expired.

The member loses their guild profile and roles. Read states, guild settings and guild folders are unchanged.

FiveCord records a MEMBER_KICK audit entry with no change list and emits Guild Audit Log Entry Create. Remaining guild sessions receive Guild Member Remove, subject to event filtering. The removed account’s sessions receive Guild Delete.

Rate limit

20 requests per 10 seconds for each authenticated user and guild ID, on the guild:member:remove::guild_id bucket.

Transfer guild ownership

POST/v1/guilds/{guild_id}/transfer-ownershipBotAudit reasonMFA

Transfers guild ownership to another current member and returns the updated guild object. Requires the caller to be the current owner. Emits a Guild Update Gateway event.

Limitations

• No permission bit substitutes for ownership.
• The target must be a current member.
• A bot target returns 400 CANNOT_TRANSFER_OWNERSHIP_TO_BOT.

The operation requires the sudo verification fields. A bot credential needs no proof. An account without a usable proof receives 403 SUDO_MODE_REQUIRED, whose payload names its available proofs in methods, reporting totp, webauthn, and backup_codes.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Request headers

Field	Type	Description
X-FiveCord-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 password, as defined by the sudo verification fields
mfa_method?	string	The second factor to verify, either totp or webauthn
mfa_code?	string	The authenticator code, required when the method is totp (1-32 characters)
webauthn_response?	WebAuthn assertion object	The assertion produced when the method is webauthn
webauthn_challenge?	string	The challenge bound to the WebAuthn assertion

Response

Status	Body	Condition
200	guild object	Ownership was transferred
400	error response	Supplied password or authenticator code is wrong, or the target is a bot account
403	error response	Guild is unavailable, sudo mode is absent, or the caller is not the guild owner
403	error response	Guild record exists while no Gateway process serves it, returning ACCESS_DENIED
404	error response	Guild does not exist, returning UNKNOWN_GUILD, or the target is not a member, returning UNKNOWN_MEMBER

Side effects

The operation changes only the guild’s owner_id. The outgoing owner keeps every role, permission overwrite, and membership they held.

It records a GUILD_UPDATE audit entry naming the previous and new owner in its change list, emits Guild Audit Log Entry Create, and emits Guild Update to every session that can see the guild. A request naming the current owner changes nothing and records no audit entry. The audit log response has no options member for this entry.

An account holding a TOTP secret or a registered WebAuthn credential also receives a reissued sudo proof. A bot credential and an account whose only proof was a password receive X-FiveCord-Sudo-Mode-JWT only when the request itself has one.

Rate limit

20 requests per 10 seconds for each authenticated user and guild ID, on the shared guild:update::guild_id bucket.

Add guild member role

PUT/v1/guilds/{guild_id}/members/{user_id}/roles/{role_id}BotAudit reason

Adds one role to a member and returns 204 with an empty body. Requires membership, MANAGE_ROLES, and hierarchy authority over the role. Emits a Guild Member Update Gateway event.

Limitations

• The guild owner bypasses the permission and the hierarchy check.
• The everyone role cannot be assigned and is rejected with the field code INVALID_ROLE_ID.

MANAGE_ROLES is an elevated permission, so a caller who is not the guild owner needs an enrolled multi-factor authenticator while the guild MFA level is elevated.

The guild owner receives 404 UNKNOWN_ROLE for a role that does not exist in the guild. Any other caller receives 403 MISSING_PERMISSIONS.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The ID of the target member
role_id	snowflake	The ID of the role to add

Response

Status	Body	Condition
204	empty	Role is present on the member
4001	error response	Role is the everyone role, or the caller holds MANAGE_ROLES without an enrolled authenticator in an elevated-MFA guild
403	error response	Guild is unavailable, the caller is not a member, MANAGE_ROLES is absent, or hierarchy authority over the role is absent
404	error response	Guild does not exist, returning UNKNOWN_GUILD
404	error response	Target is not a member, returning UNKNOWN_MEMBER
404	error response	Guild owner named a role that does not exist, returning UNKNOWN_ROLE

¹ The missing-authenticator error code is TWO_FACTOR_REQUIRED, returned only after the permission itself has been confirmed

Side effects

Adding a new role makes a temporary membership permanent. The operation records a MEMBER_ROLE_UPDATE audit entry and emits Guild Audit Log Entry Create and Guild Member Update. An unchanged role set still emits Guild Member Update and records no audit entry.

The audit log response names the role with the role_name option and through the change list.

Rate limit

20 requests per 10 seconds for each authenticated user and guild ID, on the guild:member:role:add::guild_id bucket.

Remove guild member role

DELETE/v1/guilds/{guild_id}/members/{user_id}/roles/{role_id}BotAudit reason

Removes one role from a member and returns 204 with an empty body. Requires membership, MANAGE_ROLES, and hierarchy authority over the role. Emits a Guild Member Update Gateway event.

Limitations

• The guild owner bypasses the permission and the hierarchy check.
• The everyone role cannot be removed and is rejected with the field code INVALID_ROLE_ID.

MANAGE_ROLES is an elevated permission, so a caller who is not the guild owner needs an enrolled multi-factor authenticator while the guild MFA level is elevated. A role that does not exist is reported the same way as for Add guild member role.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The ID of the target member
role_id	snowflake	The ID of the role to remove

Response

Status	Body	Condition
204	empty	Role is absent from the member
4001	error response	Role is the everyone role, or the caller holds MANAGE_ROLES without an enrolled authenticator in an elevated-MFA guild
403	error response	Guild is unavailable, the caller is not a member, MANAGE_ROLES is absent, or hierarchy authority over the role is absent
404	error response	Guild does not exist, returning UNKNOWN_GUILD
404	error response	Target is not a member, returning UNKNOWN_MEMBER
404	error response	Guild owner named a role that does not exist, returning UNKNOWN_ROLE

¹ The missing-authenticator error code is TWO_FACTOR_REQUIRED, returned only after the permission itself has been confirmed

Side effects

The operation records a MEMBER_ROLE_UPDATE audit entry and emits Guild Audit Log Entry Create and Guild Member Update. A role the member did not hold still emits Guild Member Update and records no audit entry. Removing a role does not change whether the membership is temporary.

Rate limit

20 requests per 10 seconds for each authenticated user and guild ID, on the guild:member:role:remove::guild_id bucket.