> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guilt.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Guild Management HTTP Methods for the alterself REST API

> Manage guilds, members, roles, and moderation using alterself's bot.http guild methods. Covers fetching, editing, leaving, joining, bans, kicks, and roles.

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.

```python theme={null}
g = await bot.http.fetch_guild(guild_id)
```

<ParamField path="guild_id" type="int | str" required>
  The ID of the guild to fetch.
</ParamField>

**Returns:** A `dict` representing the [Guild object](https://discord.com/developers/docs/resources/guild#guild-object).

***

### edit\_guild

Modify a guild's settings. Your account must have the **Manage Guild** permission.

```python theme={null}
g = await bot.http.edit_guild(guild_id, name="New Name")
```

<ParamField path="guild_id" type="int | str" required>
  The ID of the guild to modify.
</ParamField>

<ParamField path="name" type="str">
  The new guild name. Between 2 and 100 characters.
</ParamField>

<ParamField path="description" type="str">
  The guild description. Only available for Community guilds.
</ParamField>

<ParamField path="preferred_locale" type="str">
  The preferred locale code (e.g. `"en-US"`, `"de"`) for the guild's system messages and discovery listing.
</ParamField>

**Returns:** The updated Guild object as a `dict`.

***

### leave\_guild

Leave a guild that your account is currently a member of.

```python theme={null}
await bot.http.leave_guild(guild_id)
```

<ParamField path="guild_id" type="int | str" required>
  The ID of the guild to leave.
</ParamField>

**Returns:** `None` on success.

<Warning>
  If your account is the guild owner, you cannot leave. You must first transfer ownership to another member.
</Warning>

***

### fetch\_guild\_channels

Retrieve a list of all channels in a guild, including text channels, voice channels, categories, and any active threads.

```python theme={null}
chs = await bot.http.fetch_guild_channels(guild_id)
```

<ParamField path="guild_id" type="int | str" required>
  The ID of the target guild.
</ParamField>

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

```python theme={null}
mems = await bot.http.fetch_guild_members(guild_id, limit=1000)
```

<ParamField path="guild_id" type="int | str" required>
  The ID of the target guild.
</ParamField>

<ParamField path="limit" type="int">
  Number of members to return. Maximum `1000`. Defaults to `1`.
</ParamField>

<ParamField path="after" type="int | str">
  Return members with IDs greater than this value. Use for pagination through large member lists.
</ParamField>

**Returns:** A `list[dict]` of GuildMember objects.

***

### search\_guild\_members

Search for guild members whose username or nickname starts with a given query string.

```python theme={null}
mems = await bot.http.search_guild_members(guild_id, query="alice")
```

<ParamField path="guild_id" type="int | str" required>
  The ID of the guild to search within.
</ParamField>

<ParamField path="query" type="str" required>
  The prefix to search for. Case-insensitive.
</ParamField>

<ParamField path="limit" type="int">
  Maximum number of results to return. Between `1` and `1000`. Defaults to `1`.
</ParamField>

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

```python theme={null}
await bot.http.join_guild("abc123")  # invite code
```

<ParamField path="invite_code" type="str" required>
  The invite code (the part after `discord.gg/`). Do not include the full URL.
</ParamField>

**Returns:** A `dict` containing the invite and the guild you joined.

<Warning>
  Discord actively monitors rapid guild-join patterns. Use `join_guild` sparingly and with realistic delays to avoid triggering automated account flags.
</Warning>

***

## Moderation

### kick

Remove a member from a guild. They can rejoin with an active invite.

```python theme={null}
await bot.http.kick(guild_id, user_id, reason="spam")
```

<ParamField path="guild_id" type="int | str" required>
  The guild to kick the member from.
</ParamField>

<ParamField path="user_id" type="int | str" required>
  The ID of the member to kick.
</ParamField>

<ParamField path="reason" type="str">
  A reason string included in the guild's audit log. Optional but recommended.
</ParamField>

**Returns:** `None` on success.

***

### ban

Permanently ban a member from a guild, optionally deleting their recent message history.

```python theme={null}
await bot.http.ban(guild_id, user_id, delete_message_seconds=86400, reason="spam")
```

<ParamField path="guild_id" type="int | str" required>
  The guild to ban the user from.
</ParamField>

<ParamField path="user_id" type="int | str" required>
  The ID of the user to ban.
</ParamField>

<ParamField path="delete_message_seconds" type="int">
  Number of seconds of message history to delete, up to `604800` (7 days). Defaults to `0`.
</ParamField>

<ParamField path="reason" type="str">
  Audit log reason for the ban.
</ParamField>

**Returns:** `None` on success.

***

### unban

Revoke an existing ban, allowing the user to rejoin with an active invite.

```python theme={null}
await bot.http.unban(guild_id, user_id)
```

<ParamField path="guild_id" type="int | str" required>
  The guild to lift the ban from.
</ParamField>

<ParamField path="user_id" type="int | str" required>
  The ID of the previously-banned user.
</ParamField>

**Returns:** `None` on success.

***

### fetch\_bans

Retrieve the full list of active bans in a guild.

```python theme={null}
bans = await bot.http.fetch_bans(guild_id)
```

<ParamField path="guild_id" type="int | str" required>
  The guild whose ban list you want to retrieve.
</ParamField>

**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`.

```python theme={null}
roles = await bot.http.fetch_roles(guild_id)
```

<ParamField path="guild_id" type="int | str" required>
  The target guild.
</ParamField>

**Returns:** A `list[dict]` of Role objects, ordered by position.

***

### create\_role

Create a new role in a guild. Requires the **Manage Roles** permission.

```python theme={null}
role = await bot.http.create_role(guild_id, name="VIP", color=0xFFD700)
```

<ParamField path="guild_id" type="int | str" required>
  The guild to create the role in.
</ParamField>

<ParamField path="name" type="str">
  The name of the new role. Defaults to `"new role"` if omitted.
</ParamField>

<ParamField path="color" type="int">
  The role's display color as a 24-bit integer (e.g. `0xFFD700` for gold). Defaults to `0` (no colour).
</ParamField>

<ParamField path="hoist" type="bool">
  Whether the role should be displayed separately in the member list. Defaults to `False`.
</ParamField>

<ParamField path="mentionable" type="bool">
  Whether the role can be @mentioned by regular members. Defaults to `False`.
</ParamField>

<ParamField path="permissions" type="str">
  A bitfield string representing the permissions to grant. Defaults to the guild's `@everyone` permissions.
</ParamField>

**Returns:** The newly created Role object as a `dict`.

***

### edit\_role

Modify an existing role's properties.

```python theme={null}
role = await bot.http.edit_role(guild_id, role_id, name="Elite")
```

<ParamField path="guild_id" type="int | str" required>
  The guild that owns the role.
</ParamField>

<ParamField path="role_id" type="int | str" required>
  The ID of the role to edit.
</ParamField>

<ParamField path="name" type="str">
  The new role name.
</ParamField>

<ParamField path="color" type="int">
  The new display colour as a 24-bit integer.
</ParamField>

<ParamField path="hoist" type="bool">
  Update whether the role is hoisted in the member list.
</ParamField>

<ParamField path="mentionable" type="bool">
  Update whether the role is mentionable.
</ParamField>

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

```python theme={null}
await bot.http.delete_role(guild_id, role_id)
```

<ParamField path="guild_id" type="int | str" required>
  The guild that owns the role.
</ParamField>

<ParamField path="role_id" type="int | str" required>
  The ID of the role to delete.
</ParamField>

**Returns:** `None` on success.

***

## Invites

### fetch\_invite

Look up information about an invite without consuming it (i.e. without joining the guild).

```python theme={null}
inv = await bot.http.fetch_invite("abc123")
```

<ParamField path="invite_code" type="str" required>
  The invite code to look up (the part after `discord.gg/`).
</ParamField>

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

```python theme={null}
await bot.http.delete_invite("abc123")
```

<ParamField path="invite_code" type="str" required>
  The invite code to delete.
</ParamField>

**Returns:** `None` on success.