Skip to main content
Guild operations in alterself are exposed through bot.http, the central rate-limit-aware REST client. All methods are async and must be awaited. From fetching a guild’s metadata to issuing bans and managing roles, every call is automatically header-spoofed and backed by the library’s bucket-level rate-limit manager, so you never have to think about 429 Too Many Requests responses yourself.

​
Guild Methods

​
fetch_guild

Retrieve the full guild object for a server your account is a member of.
​
int | str
required
The ID of the guild to fetch.
Returns: A dict representing the Guild object.

​
edit_guild

Modify a guild’s settings. Your account must have the Manage Guild permission.
​
int | str
required
The ID of the guild to modify.
​
str
The new guild name. Between 2 and 100 characters.
​
str
The guild description. Only available for Community guilds.
​
str
The preferred locale code (e.g. "en-US", "de") for the guild’s system messages and discovery listing.
Returns: The updated Guild object as a dict.

​
leave_guild

Leave a guild that your account is currently a member of.
​
int | str
required
The ID of the guild to leave.
Returns: None on success.
If your account is the guild owner, you cannot leave — you must first transfer ownership to another member.

​
fetch_guild_channels

Retrieve a list of all channels in a guild, including text channels, voice channels, categories, and any active threads.
​
int | str
required
The ID of the target guild.
Returns: A list[dict] of Channel objects.

​
fetch_guild_members

Fetch a paginated list of members in a guild. Requires the Guild Members privileged intent to be enabled on the application.
​
int | str
required
The ID of the target guild.
​
int
Number of members to return. Maximum 1000. Defaults to 1.
​
int | str
Return members with IDs greater than this value. Use for pagination through large member lists.
Returns: A list[dict] of GuildMember objects.

​
search_guild_members

Search for guild members whose username or nickname starts with a given query string.
​
int | str
required
The ID of the guild to search within.
​
str
required
The prefix to search for. Case-insensitive.
​
int
Maximum number of results to return. Between 1 and 1000. Defaults to 1.
Returns: A list[dict] of GuildMember objects whose usernames or nicknames match the query prefix.

​
join_guild

Join a guild using an invite code. This replicates the action of a user clicking an invite link.
​
str
required
The invite code (the part after discord.gg/). Do not include the full URL.
Returns: A dict containing the invite and the guild you joined.
Discord actively monitors rapid guild-join patterns. Use join_guild sparingly and with realistic delays to avoid triggering automated account flags.

​
Moderation

​
kick

Remove a member from a guild. They can rejoin with an active invite.
​
int | str
required
The guild to kick the member from.
​
int | str
required
The ID of the member to kick.
​
str
A reason string included in the guild’s audit log. Optional but recommended.
Returns: None on success.

​
ban

Permanently ban a member from a guild, optionally deleting their recent message history.
​
int | str
required
The guild to ban the user from.
​
int | str
required
The ID of the user to ban.
​
int
Number of seconds of message history to delete, up to 604800 (7 days). Defaults to 0.
​
str
Audit log reason for the ban.
Returns: None on success.

​
unban

Revoke an existing ban, allowing the user to rejoin with an active invite.
​
int | str
required
The guild to lift the ban from.
​
int | str
required
The ID of the previously-banned user.
Returns: None on success.

​
fetch_bans

Retrieve the full list of active bans in a guild.
​
int | str
required
The guild whose ban list you want to retrieve.
Returns: A list[dict], each containing a reason string and a partial user object.

​
Roles

​
fetch_roles

Retrieve all roles defined in a guild, including @everyone.
​
int | str
required
The target guild.
Returns: A list[dict] of Role objects, ordered by position.

​
create_role

Create a new role in a guild. Requires the Manage Roles permission.
​
int | str
required
The guild to create the role in.
​
str
The name of the new role. Defaults to "new role" if omitted.
​
int
The role’s display color as a 24-bit integer (e.g. 0xFFD700 for gold). Defaults to 0 (no colour).
​
bool
Whether the role should be displayed separately in the member list. Defaults to False.
​
bool
Whether the role can be @mentioned by regular members. Defaults to False.
​
str
A bitfield string representing the permissions to grant. Defaults to the guild’s @everyone permissions.
Returns: The newly created Role object as a dict.

​
edit_role

Modify an existing role’s properties.
​
int | str
required
The guild that owns the role.
​
int | str
required
The ID of the role to edit.
​
str
The new role name.
​
int
The new display colour as a 24-bit integer.
​
bool
Update whether the role is hoisted in the member list.
​
bool
Update whether the role is mentionable.
Returns: The updated Role object as a dict.

​
delete_role

Permanently delete a role from a guild. Members who held that role lose it immediately.
​
int | str
required
The guild that owns the role.
​
int | str
required
The ID of the role to delete.
Returns: None on success.

​
Invites

​
fetch_invite

Look up information about an invite without consuming it (i.e. without joining the guild).
​
str
required
The invite code to look up (the part after discord.gg/).
Returns: An Invite object dict containing metadata about the destination guild, channel, and inviter.

​
delete_invite

Revoke an invite, preventing anyone from using it to join the guild. Requires Manage Guild or Manage Channels permissions.
​
str
required
The invite code to delete.
Returns: None on success.