Servers

The following section documents everything related to servers.

Models

BaseServer

Attributes

• emojis
• id
• members
• state

Methods

• async add_bot
• async ban
• async bulk_edit_role_ranks
• async create_category
• async create_channel
• async create_role
• async create_server_emoji
• async create_text_channel
• async create_voice_channel
• async delete
• async delete_category
• async edit
• async edit_category
• async fetch
• async fetch_bans
• async fetch_emojis
• async fetch_invites
• async fetch_member
• async fetch_member_list
• async fetch_members
• async fetch_role
• def get_emoji
• def get_member
• async join
• async kick
• async leave
• async mark_server_as_read
• async query_members_by_name
• async report
• async set_default_permissions
• async set_role_permissions
• async subscribe
• async unban

class stoat.BaseServer(*, state, id)

Represents a server on Stoat.

This inherits from Base.

get_emoji(emoji_id, /)

Retrieves a server emoji from cache.

Parameters:

emoji_id (str) – The emoji ID.

Returns:

The emoji or None if not found.

Return type:

Optional[ServerEmoji]

get_member(user_id, /)

Retrieves a server member from cache.

Parameters:

user_id (str) – The user ID.

Returns:

The member or None if not found.

Return type:

Optional[Member]

property emojis

Returns all emojis of this server.

Type:

Mapping[str, ServerEmoji]

property members

Returns all members of this server.

Type:

Mapping[str, Member]

await add_bot(bot, *, http_overrides=None)

This function is a coroutine.

Invites a bot to a server or group.

You must have manage_server to do this.

For servers, fires ServerCreateEvent for bot, ServerMemberJoinEvent and MessageCreateEvent for all server members.

Note

This can only be used by non-bot accounts.

Parameters:

• bot (ULIDOr[Union[BaseBot, BaseUser]]) – The bot.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.

• Forbidden – Possible values for type:

  Value	Reason
  Banned	The bot was banned in target server.
  BotIsPrivate	You do not own the bot to add it.
  MissingPermission	You do not have the proper permissions to add bots.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The bot/server was not found.

• Conflict – Possible values for type:

  Value	Reason
  AlreadyInServer	The bot is already in server.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await ban(user, *, http_overrides=None, reason=None)

This function is a coroutine.

Bans an user from the server.

You must have ban_members to do this.

May fire ServerMemberRemoveEvent for banned user and all server members.

Parameters:

• user (Union[str, BaseUser, BaseMember]) – The user to ban from the server.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• reason (Optional[str]) – The ban reason. Can be only up to 1024 characters long.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to ban yourself.
  FailedValidation	The payload was invalid.
  InvalidOperation	You tried to ban server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created ban.

Return type:

Ban

await bulk_edit_role_ranks(ranks, *, http_overrides=None)

This function is a coroutine.

Edits ranks of all roles in bulk.

You must have manage_roles to do this.

Fires ServerRoleRanksUpdateEvent for all server members.

Parameters:

• ranks (List[ULIDOr[BaseRole]]) –

  A list of roles that should be reordered, where their position in list represents their new rank.

  For example, we have following roles:

  • Owner

  • Administrator

  • Moderator

  • Member

  Passing [member_role_id, moderator_role_id, administrator_role_id, owner_role_id] would result in following hierachy:

  • Member has rank=3

  • Moderator has rank=2

  • Administrator has rank=1

  • Owner has rank=0

  Must contain all roles.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value
  InvalidOperation	One of server roles was not specified in ranks parameter.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of roles you were trying to edit rank of.
  MissingPermission	You do not have the proper permissions to edit role ranks.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The server with updated role ranks.

Return type:

Server

await create_category(title, *, http_overrides=None, channels)

This function is a coroutine.

Create a new category within server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• title (str) – The category name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• channels (List[ULIDOr[ServerChannel]]) – The channel’s IDs inside this category.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• Category – The category created in server.

await create_channel(*, http_overrides=None, type=None, name, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new text or voice channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• type (Optional[ChannelType]) – The channel type. Defaults to ChannelType.text if not provided.

• name (str) – The channel name. Must be between 1 and 32 characters.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

ServerChannel

await create_server_emoji(name, *, http_overrides=None, nsfw=None, image)

This function is a coroutine.

Creates an emoji in server.

You must have manage_customization to do this.

Fires EmojiCreateEvent for all server members.

Note

Prior to API v0.8.4, this could only be used by non-bot accounts.

Parameters:

• name (str) – The emoji name. Must be between 1 and 32 chars long. Can only contain ASCII digits, underscore and lowercase letters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• nsfw (Optional[bool]) – Whether the emoji is NSFW or not. Defaults to False.

• image (ResolvableResource) – The emoji data.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  IsBot	The current token belongs to bot account. Only applicable to instances running API whose version is lower than v0.8.3.
  TooManyEmoji	The server has too many emojis than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create emojis in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/file was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created emoji.

Return type:

ServerEmoji

await create_text_channel(name, *, http_overrides=None, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new text channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• name (str) – The channel name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

TextChannel

await create_voice_channel(name, *, http_overrides=None, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new voice channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• name (str) – The channel name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

VoiceChannel

await create_role(*, http_overrides=None, name, rank=None)

This function is a coroutine.

Creates a new server role.

You must have manage_roles to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• name (str) – The role name. Must be between 1 and 32 characters long.

• rank (Optional[int]) – The ranking position. The smaller value is, the more role takes priority.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  TooManyRoles	The server has too many roles than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of role you’re trying to create.
  MissingPermission	You do not have the proper permissions to create role in this server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The role created in server.

Return type:

Role

await delete(*, http_overrides=None)

This function is a coroutine.

Deletes a server if owner, or leaves otherwise.

Fires ServerDeleteEvent (if owner) or ServerMemberRemoveEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await delete_category(category, *, http_overrides=None)

This function is a coroutine.

Deletes a category in server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• category (ULIDOr[Category]) – The category to delete.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to delete categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.
  UnknownCategory	The category was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await edit(*, http_overrides=None, mfa_ticket=None, name=UNDEFINED, description=UNDEFINED, icon=UNDEFINED, banner=UNDEFINED, categories=UNDEFINED, system_messages=UNDEFINED, flags=UNDEFINED, discoverable=UNDEFINED, analytics=UNDEFINED, owner=UNDEFINED)

This function is a coroutine.

Edits the server.

To provide any of parameters below (except for categories, discoverable and flags), you must have manage_server.

Fires ServerUpdateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• mfa_ticket (Optional[str]) – The valid MFA ticket token. Must be provided if owner is provided as well.

• name (UndefinedOr[str]) – The new server name. Must be between 1 and 32 characters long.

• description (UndefinedOr[Optional[str]]) – The new server description. Can be only up to 1024 characters.

• icon (UndefinedOr[Optional[ResolvableResource]]) – The new server icon.

• banner (UndefinedOr[Optional[ResolvableResource]]) – The new server banner.

• categories (UndefinedOr[Optional[List[Category]]]) –

  The new server categories structure.

  You must have manage_channels.

  Deprecated since version 1.2: Due to categories rework in API v0.8.5, this parameter will be ignored on newer API versions, and was deprecated in favor of these dedicated methods:

  • create_category()

  • delete_category()

  • edit_category()

• system_messsages (UndefinedOr[Optional[SystemMessageChannels]]) – The new system message channels configuration.

• flags (UndefinedOr[ServerFlags]) – The new server flags. You must be a privileged user to provide this.

• discoverable (UndefinedOr[bool]) –

  Whether this server is public and should show up on Stoat Discover.

  The new server flags. You must be a privileged user to provide this.

• analytics (UndefinedOr[bool]) –

  Whether analytics should be collected for this server. Must be enabled in order to show up on Stoat Discover.

• owner (UndefinedOr[Union[str, BaseUser, BaseMember]]) –

  The member to transfer ownership to.

  You must own the server, or be a privileged user to provide this.

  The target user must be not a bot.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  InvalidOperation	One of these: More than 2 categories had same channel. You tried to transfer ownership to bot.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidCredentials	The provided MFA ticket was invalid.
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to edit server details.
  NotOwner	You provided owner parameter but you do not own the server or are not a privileged user.
  NotPrivileged	You provided discoverable or flags parameters but you are not a privileged user.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	One of these: The server was not found. One of channels in one of provided categories was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated server.

Return type:

Server

await edit_category(category, *, http_overrides=None, title=UNDEFINED, channels=UNDEFINED, default_permissions=UNDEFINED)

This function is a coroutine.

Edits a category in server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• category (ULIDOr[Category]) – The category to edit.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• title (UndefinedOr[str]) – The new category title.

• channels (UndefinedOr[List[ULIDOr[ServerChannel]]]) – The channel’s IDs inside this category.

• default_permissions (UndefinedOr[None]) – To remove default permissions or not.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to edit categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/ban was not found.
  UnknownCategory	The category was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated category.

Return type:

Category

await fetch(*, http_overrides=None, populate_channels=None)

This function is a coroutine.

Retrieves the server.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• populate_channels (Optional[bool]) – Whether to populate Server.channels.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

Returns:

The retrieved server.

Return type:

Server

await fetch_bans(*, http_overrides=None)

This function is a coroutine.

Retrieves all bans on the server.

You must have ban_members to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to retrieve all bans.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The ban entries.

Return type:

List[Ban]

await fetch_emojis(*, http_overrides=None)

This function is a coroutine.

Retrieves all custom ServerEmoji’s that belong to the server.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved emojis.

Return type:

List[ServerEmoji]

await fetch_invites(*, http_overrides=None)

This function is a coroutine.

Retrieves all invites that belong to the server.

You must have manage_server to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to retrieve server invites.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved invites.

Return type:

List[ServerInvite]

await fetch_member(member, *, http_overrides=None)

This function is a coroutine.

Retrieves a member.

Parameters:

• member (Union[str, BaseUser, BaseMember]) – The user to retrieve.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved member.

Return type:

Member

await fetch_members(*, http_overrides=None, exclude_offline=None)

This function is a coroutine.

Retrieves all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• exclude_offline (Optional[bool]) – Whether to exclude offline users.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved members.

Return type:

List[Member]

await fetch_member_list(*, http_overrides=None, exclude_offline=None)

This function is a coroutine.

Retrieves server member list.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• exclude_offline (Optional[bool]) – Whether to exclude offline users.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The member list.

Return type:

MemberList

await fetch_role(role, *, http_overrides=None)

This function is a coroutine.

Retrieves a server role.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• role (ULIDOr[BaseRole]) – The role to retrieve.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

Returns:

The retrieved role.

Return type:

Role

await join(*, http_overrides=None)

This function is a coroutine.

Joins the server.

Fires ServerCreateEvent for the current user, ServerMemberJoinEvent and optionally MessageCreateEvent, both for all server members.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.
  TooManyServers	You’re participating in too many servers.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  Banned	You’re banned from server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The invite/channel/server was not found.

• Conflict – Possible values for type:

  Value	Reason
  AlreadyInServer	The user is already in server.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The server you just joined.

Return type:

Server

await kick(member, *, http_overrides=None)

This function is a coroutine.

Kicks a member from the server.

Fires ServerMemberRemoveEvent for kicked user and all server members.

Parameters:

• member (Union[str, BaseUser, BaseMember]) – The member to kick.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to kick yourself.
  InvalidOperation	You tried to kick server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await leave(*, http_overrides=None, silent=None)

This function is a coroutine.

Leaves a server if not owner, or deletes otherwise.

Fires ServerMemberRemoveEvent or ServerDeleteEvent (if owner) for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• silent (Optional[bool]) – Whether to silently leave server or not.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await mark_server_as_read(*, http_overrides=None)

This function is a coroutine.

Marks all channels in a server as read.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await query_members_by_name(query, *, http_overrides=None)

This function is a coroutine.

Query members by a given name.

Warning

This API is not stable and may be removed in the future.

Parameters:

• query (str) – The query to search members for.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The members matched.

Return type:

List[Member]

await report(reason, *, http_overrides=None, additional_context=None)

This function is a coroutine.

Report the server to the instance moderation team.

Fires ReportCreateEvent internally (but not fired over WebSocket).

Note

This can only be used by non-bot accounts.

Parameters:

• reason (ContentReportReason) – The reason for reporting.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• additional_context (Optional[str]) – The additional context for moderation team. Can be only up to 1000 characters.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotReportYourself	You tried to report your own server.
  FailedValidation	The payload was invalid.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await set_role_permissions(role, *, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)

This function is a coroutine.

Sets permissions for the specified server role.

You must have manage_permissions to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

• role (ULIDOr[BaseRole]) – The role.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• allow (Permissions) – The permissions to allow for the specified role.

• deny (Permissions) – The permissions to deny for the specified role.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  CannotGiveMissingPermissions	Your new provided permissions contained permissions you didn’t have.
  NotElevated	Rank of your top role is higher than rank of role you’re trying to set override for.
  MissingPermission	You do not have the proper permissions to edit permissions for this role.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The updated server with new permissions.

Return type:

Server

await set_default_permissions(permissions, *, http_overrides=None)

This function is a coroutine.

Sets default permissions for everyone in a server.

You must have manage_permissions to do this.

Fires ServerUpdateEvent for all server members.

Parameters:

• permissions (Permissions) – The new permissions.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  CannotGiveMissingPermissions	Your new provided permissions contained permissions you didn’t have.
  MissingPermission	You do not have the proper permissions to edit default permissions for this server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The channel was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated server.

Return type:

Server

await subscribe()

This function is a coroutine.

Subscribes to this server.

await unban(user, *, http_overrides=None)

This function is a coroutine.

Unbans an user from the server.

You must have ban_members to do this.

Parameters:

• user (ULIDOr[BaseUser]) – The user to unban from the server.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to unban members.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

id

The ID of the entity.

Type:

str

state

The state that controls this entity.

Type:

State

PartialServer

Attributes

• analytics
• banner
• categories
• channel_ids
• default_permissions
• description
• discoverable
• emojis
• flags
• icon
• id
• internal_banner
• internal_categories
• internal_icon
• members
• name
• owner_id
• raw_default_permissions
• raw_flags
• state
• system_messages

Methods

• async add_bot
• async ban
• async bulk_edit_role_ranks
• async create_category
• async create_channel
• async create_role
• async create_server_emoji
• async create_text_channel
• async create_voice_channel
• async delete
• async delete_category
• async edit
• async edit_category
• async fetch
• async fetch_bans
• async fetch_emojis
• async fetch_invites
• async fetch_member
• async fetch_member_list
• async fetch_members
• async fetch_role
• def get_emoji
• def get_member
• async join
• async kick
• async leave
• async mark_server_as_read
• async query_members_by_name
• async report
• async set_default_permissions
• async set_role_permissions
• async subscribe
• async unban

class stoat.PartialServer(*, state, id, name, owner_id, description, channel_ids, internal_categories, system_messages, raw_default_permissions, internal_icon, internal_banner, raw_flags, discoverable, analytics)

Represents a partial server on Stoat.

Unmodified fields will have UNDEFINED value.

This inherits from BaseServer.

name

The new server’s name.

Type:

UndefinedOr[str]

owner_id

The new user’s ID who owns this server.

Type:

UndefinedOr[str]

description

The new server’s description.

Type:

UndefinedOr[Optional[str]]

channel_ids

The server’s channels now.

Type:

UndefinedOr[List[str]]

internal_categories

The server’s categories now.

Type:

UndefinedOr[Optional[Union[List[Category], Dict[str, Category]]]]

system_messages

The new server’s system message assignments.

Type:

UndefinedOr[Optional[SystemMessageChannels]]

raw_default_permissions

The raw value of new default permissions for everyone.

Type:

UndefinedOr[int]

internal_icon

The new server’s icon, if any.

Type:

UndefinedOr[Optional[StatelessAsset]]

internal_banner

The new server’s banner, if any.

Type:

UndefinedOr[Optional[StatelessAsset]]

raw_flags

The new server’s flags raw value.

Type:

UndefinedOr[int]

discoverable

Whether the server is publicly discoverable.

Type:

UndefinedOr[bool]

analytics

Whether the server activity is being analyzed in real-time.

Type:

UndefinedOr[bool]

property categories

The server’s categories now.

Type:

UndefinedOr[Optional[List[Category]]]

property default_permissions

The new default permissions for everyone.

Type:

UndefinedOr[Permissions]

property flags

The new server’s flags.

Type:

UndefinedOr[ServerFlags]

property icon

The stateful server icon.

Type:

UndefinedOr[Optional[Asset]]

property banner

The stateful server banner.

Type:

UndefinedOr[Optional[Asset]]

await add_bot(bot, *, http_overrides=None)

This function is a coroutine.

Invites a bot to a server or group.

You must have manage_server to do this.

For servers, fires ServerCreateEvent for bot, ServerMemberJoinEvent and MessageCreateEvent for all server members.

Note

This can only be used by non-bot accounts.

Parameters:

• bot (ULIDOr[Union[BaseBot, BaseUser]]) – The bot.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.

• Forbidden – Possible values for type:

  Value	Reason
  Banned	The bot was banned in target server.
  BotIsPrivate	You do not own the bot to add it.
  MissingPermission	You do not have the proper permissions to add bots.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The bot/server was not found.

• Conflict – Possible values for type:

  Value	Reason
  AlreadyInServer	The bot is already in server.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await ban(user, *, http_overrides=None, reason=None)

This function is a coroutine.

Bans an user from the server.

You must have ban_members to do this.

May fire ServerMemberRemoveEvent for banned user and all server members.

Parameters:

• user (Union[str, BaseUser, BaseMember]) – The user to ban from the server.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• reason (Optional[str]) – The ban reason. Can be only up to 1024 characters long.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to ban yourself.
  FailedValidation	The payload was invalid.
  InvalidOperation	You tried to ban server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created ban.

Return type:

Ban

await bulk_edit_role_ranks(ranks, *, http_overrides=None)

This function is a coroutine.

Edits ranks of all roles in bulk.

You must have manage_roles to do this.

Fires ServerRoleRanksUpdateEvent for all server members.

Parameters:

• ranks (List[ULIDOr[BaseRole]]) –

  A list of roles that should be reordered, where their position in list represents their new rank.

  For example, we have following roles:

  • Owner

  • Administrator

  • Moderator

  • Member

  Passing [member_role_id, moderator_role_id, administrator_role_id, owner_role_id] would result in following hierachy:

  • Member has rank=3

  • Moderator has rank=2

  • Administrator has rank=1

  • Owner has rank=0

  Must contain all roles.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value
  InvalidOperation	One of server roles was not specified in ranks parameter.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of roles you were trying to edit rank of.
  MissingPermission	You do not have the proper permissions to edit role ranks.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The server with updated role ranks.

Return type:

Server

await create_category(title, *, http_overrides=None, channels)

This function is a coroutine.

Create a new category within server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• title (str) – The category name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• channels (List[ULIDOr[ServerChannel]]) – The channel’s IDs inside this category.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• Category – The category created in server.

await create_channel(*, http_overrides=None, type=None, name, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new text or voice channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• type (Optional[ChannelType]) – The channel type. Defaults to ChannelType.text if not provided.

• name (str) – The channel name. Must be between 1 and 32 characters.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

ServerChannel

await create_role(*, http_overrides=None, name, rank=None)

This function is a coroutine.

Creates a new server role.

You must have manage_roles to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• name (str) – The role name. Must be between 1 and 32 characters long.

• rank (Optional[int]) – The ranking position. The smaller value is, the more role takes priority.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  TooManyRoles	The server has too many roles than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of role you’re trying to create.
  MissingPermission	You do not have the proper permissions to create role in this server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The role created in server.

Return type:

Role

await create_server_emoji(name, *, http_overrides=None, nsfw=None, image)

This function is a coroutine.

Creates an emoji in server.

You must have manage_customization to do this.

Fires EmojiCreateEvent for all server members.

Note

Prior to API v0.8.4, this could only be used by non-bot accounts.

Parameters:

• name (str) – The emoji name. Must be between 1 and 32 chars long. Can only contain ASCII digits, underscore and lowercase letters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• nsfw (Optional[bool]) – Whether the emoji is NSFW or not. Defaults to False.

• image (ResolvableResource) – The emoji data.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  IsBot	The current token belongs to bot account. Only applicable to instances running API whose version is lower than v0.8.3.
  TooManyEmoji	The server has too many emojis than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create emojis in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/file was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created emoji.

Return type:

ServerEmoji

await create_text_channel(name, *, http_overrides=None, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new text channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• name (str) – The channel name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

TextChannel

await create_voice_channel(name, *, http_overrides=None, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new voice channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• name (str) – The channel name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

VoiceChannel

await delete(*, http_overrides=None)

This function is a coroutine.

Deletes a server if owner, or leaves otherwise.

Fires ServerDeleteEvent (if owner) or ServerMemberRemoveEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await delete_category(category, *, http_overrides=None)

This function is a coroutine.

Deletes a category in server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• category (ULIDOr[Category]) – The category to delete.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to delete categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.
  UnknownCategory	The category was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await edit(*, http_overrides=None, mfa_ticket=None, name=UNDEFINED, description=UNDEFINED, icon=UNDEFINED, banner=UNDEFINED, categories=UNDEFINED, system_messages=UNDEFINED, flags=UNDEFINED, discoverable=UNDEFINED, analytics=UNDEFINED, owner=UNDEFINED)

This function is a coroutine.

Edits the server.

To provide any of parameters below (except for categories, discoverable and flags), you must have manage_server.

Fires ServerUpdateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• mfa_ticket (Optional[str]) – The valid MFA ticket token. Must be provided if owner is provided as well.

• name (UndefinedOr[str]) – The new server name. Must be between 1 and 32 characters long.

• description (UndefinedOr[Optional[str]]) – The new server description. Can be only up to 1024 characters.

• icon (UndefinedOr[Optional[ResolvableResource]]) – The new server icon.

• banner (UndefinedOr[Optional[ResolvableResource]]) – The new server banner.

• categories (UndefinedOr[Optional[List[Category]]]) –

  The new server categories structure.

  You must have manage_channels.

  Deprecated since version 1.2: Due to categories rework in API v0.8.5, this parameter will be ignored on newer API versions, and was deprecated in favor of these dedicated methods:

  • create_category()

  • delete_category()

  • edit_category()

• system_messsages (UndefinedOr[Optional[SystemMessageChannels]]) – The new system message channels configuration.

• flags (UndefinedOr[ServerFlags]) – The new server flags. You must be a privileged user to provide this.

• discoverable (UndefinedOr[bool]) –

  Whether this server is public and should show up on Stoat Discover.

  The new server flags. You must be a privileged user to provide this.

• analytics (UndefinedOr[bool]) –

  Whether analytics should be collected for this server. Must be enabled in order to show up on Stoat Discover.

• owner (UndefinedOr[Union[str, BaseUser, BaseMember]]) –

  The member to transfer ownership to.

  You must own the server, or be a privileged user to provide this.

  The target user must be not a bot.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  InvalidOperation	One of these: More than 2 categories had same channel. You tried to transfer ownership to bot.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidCredentials	The provided MFA ticket was invalid.
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to edit server details.
  NotOwner	You provided owner parameter but you do not own the server or are not a privileged user.
  NotPrivileged	You provided discoverable or flags parameters but you are not a privileged user.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	One of these: The server was not found. One of channels in one of provided categories was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated server.

Return type:

Server

await edit_category(category, *, http_overrides=None, title=UNDEFINED, channels=UNDEFINED, default_permissions=UNDEFINED)

This function is a coroutine.

Edits a category in server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• category (ULIDOr[Category]) – The category to edit.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• title (UndefinedOr[str]) – The new category title.

• channels (UndefinedOr[List[ULIDOr[ServerChannel]]]) – The channel’s IDs inside this category.

• default_permissions (UndefinedOr[None]) – To remove default permissions or not.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to edit categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/ban was not found.
  UnknownCategory	The category was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated category.

Return type:

Category

property emojis

Returns all emojis of this server.

Type:

Mapping[str, ServerEmoji]

await fetch(*, http_overrides=None, populate_channels=None)

This function is a coroutine.

Retrieves the server.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• populate_channels (Optional[bool]) – Whether to populate Server.channels.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

Returns:

The retrieved server.

Return type:

Server

await fetch_bans(*, http_overrides=None)

This function is a coroutine.

Retrieves all bans on the server.

You must have ban_members to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to retrieve all bans.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The ban entries.

Return type:

List[Ban]

await fetch_emojis(*, http_overrides=None)

This function is a coroutine.

Retrieves all custom ServerEmoji’s that belong to the server.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved emojis.

Return type:

List[ServerEmoji]

await fetch_invites(*, http_overrides=None)

This function is a coroutine.

Retrieves all invites that belong to the server.

You must have manage_server to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to retrieve server invites.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved invites.

Return type:

List[ServerInvite]

await fetch_member(member, *, http_overrides=None)

This function is a coroutine.

Retrieves a member.

Parameters:

• member (Union[str, BaseUser, BaseMember]) – The user to retrieve.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved member.

Return type:

Member

await fetch_member_list(*, http_overrides=None, exclude_offline=None)

This function is a coroutine.

Retrieves server member list.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• exclude_offline (Optional[bool]) – Whether to exclude offline users.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The member list.

Return type:

MemberList

await fetch_members(*, http_overrides=None, exclude_offline=None)

This function is a coroutine.

Retrieves all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• exclude_offline (Optional[bool]) – Whether to exclude offline users.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved members.

Return type:

List[Member]

await fetch_role(role, *, http_overrides=None)

This function is a coroutine.

Retrieves a server role.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• role (ULIDOr[BaseRole]) – The role to retrieve.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

Returns:

The retrieved role.

Return type:

Role

get_emoji(emoji_id, /)

Retrieves a server emoji from cache.

Parameters:

emoji_id (str) – The emoji ID.

Returns:

The emoji or None if not found.

Return type:

Optional[ServerEmoji]

get_member(user_id, /)

Retrieves a server member from cache.

Parameters:

user_id (str) – The user ID.

Returns:

The member or None if not found.

Return type:

Optional[Member]

id

The ID of the entity.

Type:

str

await join(*, http_overrides=None)

This function is a coroutine.

Joins the server.

Fires ServerCreateEvent for the current user, ServerMemberJoinEvent and optionally MessageCreateEvent, both for all server members.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.
  TooManyServers	You’re participating in too many servers.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  Banned	You’re banned from server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The invite/channel/server was not found.

• Conflict – Possible values for type:

  Value	Reason
  AlreadyInServer	The user is already in server.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The server you just joined.

Return type:

Server

await kick(member, *, http_overrides=None)

This function is a coroutine.

Kicks a member from the server.

Fires ServerMemberRemoveEvent for kicked user and all server members.

Parameters:

• member (Union[str, BaseUser, BaseMember]) – The member to kick.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to kick yourself.
  InvalidOperation	You tried to kick server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await leave(*, http_overrides=None, silent=None)

This function is a coroutine.

Leaves a server if not owner, or deletes otherwise.

Fires ServerMemberRemoveEvent or ServerDeleteEvent (if owner) for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• silent (Optional[bool]) – Whether to silently leave server or not.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await mark_server_as_read(*, http_overrides=None)

This function is a coroutine.

Marks all channels in a server as read.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

property members

Returns all members of this server.

Type:

Mapping[str, Member]

await query_members_by_name(query, *, http_overrides=None)

This function is a coroutine.

Query members by a given name.

Warning

This API is not stable and may be removed in the future.

Parameters:

• query (str) – The query to search members for.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The members matched.

Return type:

List[Member]

await report(reason, *, http_overrides=None, additional_context=None)

This function is a coroutine.

Report the server to the instance moderation team.

Fires ReportCreateEvent internally (but not fired over WebSocket).

Note

This can only be used by non-bot accounts.

Parameters:

• reason (ContentReportReason) – The reason for reporting.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• additional_context (Optional[str]) – The additional context for moderation team. Can be only up to 1000 characters.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotReportYourself	You tried to report your own server.
  FailedValidation	The payload was invalid.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await set_default_permissions(permissions, *, http_overrides=None)

This function is a coroutine.

Sets default permissions for everyone in a server.

You must have manage_permissions to do this.

Fires ServerUpdateEvent for all server members.

Parameters:

• permissions (Permissions) – The new permissions.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  CannotGiveMissingPermissions	Your new provided permissions contained permissions you didn’t have.
  MissingPermission	You do not have the proper permissions to edit default permissions for this server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The channel was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated server.

Return type:

Server

await set_role_permissions(role, *, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)

This function is a coroutine.

Sets permissions for the specified server role.

You must have manage_permissions to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

• role (ULIDOr[BaseRole]) – The role.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• allow (Permissions) – The permissions to allow for the specified role.

• deny (Permissions) – The permissions to deny for the specified role.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  CannotGiveMissingPermissions	Your new provided permissions contained permissions you didn’t have.
  NotElevated	Rank of your top role is higher than rank of role you’re trying to set override for.
  MissingPermission	You do not have the proper permissions to edit permissions for this role.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The updated server with new permissions.

Return type:

Server

state

The state that controls this entity.

Type:

State

await subscribe()

This function is a coroutine.

Subscribes to this server.

await unban(user, *, http_overrides=None)

This function is a coroutine.

Unbans an user from the server.

You must have ban_members to do this.

Parameters:

• user (ULIDOr[BaseUser]) – The user to unban from the server.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to unban members.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Server

Attributes

• analytics
• banner
• categories
• categories_as_mapping
• channel_ids
• channels
• default_permissions
• description
• discoverable
• emojis
• flags
• icon
• id
• internal_banner
• internal_categories
• internal_icon
• me
• members
• name
• nsfw
• owner
• owner_as_member
• owner_as_user
• owner_id
• raw_default_permissions
• raw_flags
• roles
• state
• system_messages

Methods

• async add_bot
• async ban
• async bulk_edit_role_ranks
• async create_category
• async create_channel
• async create_role
• async create_server_emoji
• async create_text_channel
• async create_voice_channel
• async delete
• async delete_category
• async edit
• async edit_category
• async fetch
• async fetch_bans
• async fetch_emojis
• async fetch_invites
• async fetch_member
• async fetch_member_list
• async fetch_members
• async fetch_role
• def get_category
• def get_channel
• def get_emoji
• def get_me
• def get_member
• def get_owner
• def get_owner_as_member
• def get_owner_as_user
• def is_official
• def is_verified
• async join
• async kick
• async leave
• def locally_update
• async mark_server_as_read
• def permissions_for
• def prepare_cached
• async query_members_by_name
• async report
• async set_default_permissions
• async set_role_permissions
• async subscribe
• def to_dict
• async unban
• def upsert_role

class stoat.Server(*, state, id, owner_id, name, description, internal_channels, internal_categories, system_messages, roles, raw_default_permissions, internal_icon, internal_banner, raw_flags, nsfw, analytics, discoverable)

Represents a server on Stoat.

This inherits from BaseServer.

owner_id

The user’s ID who owns this server.

Type:

str

name

The server’s name.

Type:

str

description

The server’s description.

Type:

Optional[str]

internal_categories

The server’s categories.

Type:

Optional[Union[List[Category], Dict[str, Category]]]

system_messages

The configuration for sending system event messages.

Type:

Optional[SystemMessageChannels]

roles

The server’s roles.

Type:

Dict[str, Role]

raw_default_permissions

The raw value of default permissions for everyone.

Type:

int

internal_icon

The stateless server’s icon.

Type:

Optional[StatelessAsset]

internal_banner

The stateless server’s banner.

Type:

Optional[StatelessAsset]

raw_flags

The server’s flags raw value.

Type:

int

nsfw

Whether the server is flagged as not safe for work.

Type:

bool

analytics

Whether the server activity is being analyzed in real-time.

Type:

bool

discoverable

Whether the server is publicly discoverable.

Type:

bool

get_category(category_id, /)

Retrieves a server category from cache.

Parameters:

category_id (str) – The category ID.

Returns:

The category or None if not found.

Return type:

Optional[Category]

get_channel(channel_id, /)

Retrieves a server channel from cache.

Parameters:

channel_id (str) – The channel ID.

Returns:

The channel or None if not found.

Return type:

Optional[ServerChannel]

get_me()

Optional[Member]: The own user for this server.

get_owner()

Optional[Union[Member, User]]: The server’s owner.

get_owner_as_member()

Optional[Member]: The server’s owner.

get_owner_as_user()

Optional[User]: The server’s owner.

property banner

The server banner.

Type:

Optional[Asset]

property categories

The server’s categories.

Type:

Optional[List[Category]]

property categories_as_mapping

The server’s categories as mapping.

Type:

Optional[Dict[str, Category]]

property channel_ids

The IDs of channels within this server.

Type:

List[str]

property channels

The channels within this server.

Type:

List[ServerChannel]

property default_permissions

The default permissions for everyone.

Type:

Permissions

property flags

The server’s flags.

Type:

ServerFlags

property icon

The server icon.

Type:

Optional[Asset]

property me

The own user for this server.

Type:

Member

property owner

The server’s owner.

Type:

Union[Member, User]

property owner_as_member

The server’s owner.

Type:

Member

property owner_as_user

The server’s owner.

Type:

User

is_verified()

bool: Whether the server is verified.

is_official()

bool: Whether the server is ran by Stoat team.

locally_update(data, /)

Locally updates server with provided data.

Warning

This is called by library internally to keep cache up to date. You likely want to use BaseServer.edit() method instead.

permissions_for(member, /, *, safe=True, with_ownership=True, include_timeout=True)

Calculate permissions for given member.

Parameters:

• member (Union[Member, User]) – The member to calculate permissions for.

• safe (bool) – Whether to raise exception or not if role is missing in cache.

• with_ownership (bool) – Whether to account for ownership.

• include_timeout (bool) – Whether to account for timeout.

Raises:

NoData – The role is not found in cache.

Returns:

The calculated permissions.

Return type:

Permissions

prepare_cached()

List[ServerChannel]: Prepares the server to be cached.

to_dict(*, with_channels=False)

dict: Convert server to raw data.

Parameters:

with_channels (bool) – Whether to include channel objects instead of their IDs in channels key when serializing. Defaults to False.

upsert_role(role, /)

Locally upserts role into Server.roles mapping.

Warning

This is called by library internally to keep cache up to date. You likely want to use BaseServer.create_role() or BaseRole.edit() instead.

Parameters:

role (Union[PartialRole, Role]) – The role to upsert.

await add_bot(bot, *, http_overrides=None)

This function is a coroutine.

Invites a bot to a server or group.

You must have manage_server to do this.

For servers, fires ServerCreateEvent for bot, ServerMemberJoinEvent and MessageCreateEvent for all server members.

Note

This can only be used by non-bot accounts.

Parameters:

• bot (ULIDOr[Union[BaseBot, BaseUser]]) – The bot.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.

• Forbidden – Possible values for type:

  Value	Reason
  Banned	The bot was banned in target server.
  BotIsPrivate	You do not own the bot to add it.
  MissingPermission	You do not have the proper permissions to add bots.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The bot/server was not found.

• Conflict – Possible values for type:

  Value	Reason
  AlreadyInServer	The bot is already in server.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await ban(user, *, http_overrides=None, reason=None)

This function is a coroutine.

Bans an user from the server.

You must have ban_members to do this.

May fire ServerMemberRemoveEvent for banned user and all server members.

Parameters:

• user (Union[str, BaseUser, BaseMember]) – The user to ban from the server.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• reason (Optional[str]) – The ban reason. Can be only up to 1024 characters long.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to ban yourself.
  FailedValidation	The payload was invalid.
  InvalidOperation	You tried to ban server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created ban.

Return type:

Ban

await bulk_edit_role_ranks(ranks, *, http_overrides=None)

This function is a coroutine.

Edits ranks of all roles in bulk.

You must have manage_roles to do this.

Fires ServerRoleRanksUpdateEvent for all server members.

Parameters:

• ranks (List[ULIDOr[BaseRole]]) –

  A list of roles that should be reordered, where their position in list represents their new rank.

  For example, we have following roles:

  • Owner

  • Administrator

  • Moderator

  • Member

  Passing [member_role_id, moderator_role_id, administrator_role_id, owner_role_id] would result in following hierachy:

  • Member has rank=3

  • Moderator has rank=2

  • Administrator has rank=1

  • Owner has rank=0

  Must contain all roles.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value
  InvalidOperation	One of server roles was not specified in ranks parameter.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of roles you were trying to edit rank of.
  MissingPermission	You do not have the proper permissions to edit role ranks.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The server with updated role ranks.

Return type:

Server

await create_category(title, *, http_overrides=None, channels)

This function is a coroutine.

Create a new category within server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• title (str) – The category name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• channels (List[ULIDOr[ServerChannel]]) – The channel’s IDs inside this category.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• Category – The category created in server.

await create_channel(*, http_overrides=None, type=None, name, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new text or voice channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• type (Optional[ChannelType]) – The channel type. Defaults to ChannelType.text if not provided.

• name (str) – The channel name. Must be between 1 and 32 characters.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

ServerChannel

await create_role(*, http_overrides=None, name, rank=None)

This function is a coroutine.

Creates a new server role.

You must have manage_roles to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• name (str) – The role name. Must be between 1 and 32 characters long.

• rank (Optional[int]) – The ranking position. The smaller value is, the more role takes priority.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  TooManyRoles	The server has too many roles than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of role you’re trying to create.
  MissingPermission	You do not have the proper permissions to create role in this server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The role created in server.

Return type:

Role

await create_server_emoji(name, *, http_overrides=None, nsfw=None, image)

This function is a coroutine.

Creates an emoji in server.

You must have manage_customization to do this.

Fires EmojiCreateEvent for all server members.

Note

Prior to API v0.8.4, this could only be used by non-bot accounts.

Parameters:

• name (str) – The emoji name. Must be between 1 and 32 chars long. Can only contain ASCII digits, underscore and lowercase letters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• nsfw (Optional[bool]) – Whether the emoji is NSFW or not. Defaults to False.

• image (ResolvableResource) – The emoji data.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  IsBot	The current token belongs to bot account. Only applicable to instances running API whose version is lower than v0.8.3.
  TooManyEmoji	The server has too many emojis than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create emojis in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/file was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created emoji.

Return type:

ServerEmoji

await create_text_channel(name, *, http_overrides=None, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new text channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• name (str) – The channel name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

TextChannel

await create_voice_channel(name, *, http_overrides=None, description=None, nsfw=None, voice=None)

This function is a coroutine.

Create a new voice channel within server.

You must have manage_channels to do this.

Fires ServerChannelCreateEvent for all server members.

Parameters:

• name (str) – The channel name. Must be between 1 and 32 characters.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• description (Optional[str]) – The channel description. Can be only up to 1024 characters.

• nsfw (Optional[bool]) – To mark channel as NSFW or not.

• voice (Optional[ChannelVoiceMetadata]) –

  The voice-specific metadata for this channel.

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyChannels	The server has too many channels than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to create channels in server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The channel created in server.

Return type:

VoiceChannel

await delete(*, http_overrides=None)

This function is a coroutine.

Deletes a server if owner, or leaves otherwise.

Fires ServerDeleteEvent (if owner) or ServerMemberRemoveEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await delete_category(category, *, http_overrides=None)

This function is a coroutine.

Deletes a category in server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• category (ULIDOr[Category]) – The category to delete.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to delete categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.
  UnknownCategory	The category was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await edit(*, http_overrides=None, mfa_ticket=None, name=UNDEFINED, description=UNDEFINED, icon=UNDEFINED, banner=UNDEFINED, categories=UNDEFINED, system_messages=UNDEFINED, flags=UNDEFINED, discoverable=UNDEFINED, analytics=UNDEFINED, owner=UNDEFINED)

This function is a coroutine.

Edits the server.

To provide any of parameters below (except for categories, discoverable and flags), you must have manage_server.

Fires ServerUpdateEvent for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• mfa_ticket (Optional[str]) – The valid MFA ticket token. Must be provided if owner is provided as well.

• name (UndefinedOr[str]) – The new server name. Must be between 1 and 32 characters long.

• description (UndefinedOr[Optional[str]]) – The new server description. Can be only up to 1024 characters.

• icon (UndefinedOr[Optional[ResolvableResource]]) – The new server icon.

• banner (UndefinedOr[Optional[ResolvableResource]]) – The new server banner.

• categories (UndefinedOr[Optional[List[Category]]]) –

  The new server categories structure.

  You must have manage_channels.

  Deprecated since version 1.2: Due to categories rework in API v0.8.5, this parameter will be ignored on newer API versions, and was deprecated in favor of these dedicated methods:

  • create_category()

  • delete_category()

  • edit_category()

• system_messsages (UndefinedOr[Optional[SystemMessageChannels]]) – The new system message channels configuration.

• flags (UndefinedOr[ServerFlags]) – The new server flags. You must be a privileged user to provide this.

• discoverable (UndefinedOr[bool]) –

  Whether this server is public and should show up on Stoat Discover.

  The new server flags. You must be a privileged user to provide this.

• analytics (UndefinedOr[bool]) –

  Whether analytics should be collected for this server. Must be enabled in order to show up on Stoat Discover.

• owner (UndefinedOr[Union[str, BaseUser, BaseMember]]) –

  The member to transfer ownership to.

  You must own the server, or be a privileged user to provide this.

  The target user must be not a bot.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  FailedValidation	The payload was invalid.
  InvalidOperation	One of these: More than 2 categories had same channel. You tried to transfer ownership to bot.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidCredentials	The provided MFA ticket was invalid.
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to edit server details.
  NotOwner	You provided owner parameter but you do not own the server or are not a privileged user.
  NotPrivileged	You provided discoverable or flags parameters but you are not a privileged user.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	One of these: The server was not found. One of channels in one of provided categories was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated server.

Return type:

Server

await edit_category(category, *, http_overrides=None, title=UNDEFINED, channels=UNDEFINED, default_permissions=UNDEFINED)

This function is a coroutine.

Edits a category in server.

You must have manage_channels to do this.

Fires ServerUpdateEvent for all server members.

Added in version 1.2.

Parameters:

• category (ULIDOr[Category]) – The category to edit.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• title (UndefinedOr[str]) – The new category title.

• channels (UndefinedOr[List[ULIDOr[ServerChannel]]]) – The channel’s IDs inside this category.

• default_permissions (UndefinedOr[None]) – To remove default permissions or not.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  TooManyCategories	The server has too many categories than allowed on this instance.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to edit categories.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/ban was not found.
  UnknownCategory	The category was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated category.

Return type:

Category

property emojis

Returns all emojis of this server.

Type:

Mapping[str, ServerEmoji]

await fetch(*, http_overrides=None, populate_channels=None)

This function is a coroutine.

Retrieves the server.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• populate_channels (Optional[bool]) – Whether to populate Server.channels.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

Returns:

The retrieved server.

Return type:

Server

await fetch_bans(*, http_overrides=None)

This function is a coroutine.

Retrieves all bans on the server.

You must have ban_members to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to retrieve all bans.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The ban entries.

Return type:

List[Ban]

await fetch_emojis(*, http_overrides=None)

This function is a coroutine.

Retrieves all custom ServerEmoji’s that belong to the server.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved emojis.

Return type:

List[ServerEmoji]

await fetch_invites(*, http_overrides=None)

This function is a coroutine.

Retrieves all invites that belong to the server.

You must have manage_server to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to retrieve server invites.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved invites.

Return type:

List[ServerInvite]

await fetch_member(member, *, http_overrides=None)

This function is a coroutine.

Retrieves a member.

Parameters:

• member (Union[str, BaseUser, BaseMember]) – The user to retrieve.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved member.

Return type:

Member

await fetch_member_list(*, http_overrides=None, exclude_offline=None)

This function is a coroutine.

Retrieves server member list.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• exclude_offline (Optional[bool]) – Whether to exclude offline users.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The member list.

Return type:

MemberList

await fetch_members(*, http_overrides=None, exclude_offline=None)

This function is a coroutine.

Retrieves all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• exclude_offline (Optional[bool]) – Whether to exclude offline users.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The retrieved members.

Return type:

List[Member]

await fetch_role(role, *, http_overrides=None)

This function is a coroutine.

Retrieves a server role.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• role (ULIDOr[BaseRole]) – The role to retrieve.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

Returns:

The retrieved role.

Return type:

Role

get_emoji(emoji_id, /)

Retrieves a server emoji from cache.

Parameters:

emoji_id (str) – The emoji ID.

Returns:

The emoji or None if not found.

Return type:

Optional[ServerEmoji]

get_member(user_id, /)

Retrieves a server member from cache.

Parameters:

user_id (str) – The user ID.

Returns:

The member or None if not found.

Return type:

Optional[Member]

id

The ID of the entity.

Type:

str

await join(*, http_overrides=None)

This function is a coroutine.

Joins the server.

Fires ServerCreateEvent for the current user, ServerMemberJoinEvent and optionally MessageCreateEvent, both for all server members.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.
  TooManyServers	You’re participating in too many servers.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  Banned	You’re banned from server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The invite/channel/server was not found.

• Conflict – Possible values for type:

  Value	Reason
  AlreadyInServer	The user is already in server.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The server you just joined.

Return type:

Server

await kick(member, *, http_overrides=None)

This function is a coroutine.

Kicks a member from the server.

Fires ServerMemberRemoveEvent for kicked user and all server members.

Parameters:

• member (Union[str, BaseUser, BaseMember]) – The member to kick.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to kick yourself.
  InvalidOperation	You tried to kick server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await leave(*, http_overrides=None, silent=None)

This function is a coroutine.

Leaves a server if not owner, or deletes otherwise.

Fires ServerMemberRemoveEvent or ServerDeleteEvent (if owner) for all server members.

Parameters:

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• silent (Optional[bool]) – Whether to silently leave server or not.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await mark_server_as_read(*, http_overrides=None)

This function is a coroutine.

Marks all channels in a server as read.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  IsBot	The current token belongs to bot account.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

property members

Returns all members of this server.

Type:

Mapping[str, Member]

await query_members_by_name(query, *, http_overrides=None)

This function is a coroutine.

Query members by a given name.

Warning

This API is not stable and may be removed in the future.

Parameters:

• query (str) – The query to search members for.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The members matched.

Return type:

List[Member]

await report(reason, *, http_overrides=None, additional_context=None)

This function is a coroutine.

Report the server to the instance moderation team.

Fires ReportCreateEvent internally (but not fired over WebSocket).

Note

This can only be used by non-bot accounts.

Parameters:

• reason (ContentReportReason) – The reason for reporting.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• additional_context (Optional[str]) – The additional context for moderation team. Can be only up to 1000 characters.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotReportYourself	You tried to report your own server.
  FailedValidation	The payload was invalid.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await set_default_permissions(permissions, *, http_overrides=None)

This function is a coroutine.

Sets default permissions for everyone in a server.

You must have manage_permissions to do this.

Fires ServerUpdateEvent for all server members.

Parameters:

• permissions (Permissions) – The new permissions.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  CannotGiveMissingPermissions	Your new provided permissions contained permissions you didn’t have.
  MissingPermission	You do not have the proper permissions to edit default permissions for this server.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The channel was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The newly updated server.

Return type:

Server

await set_role_permissions(role, *, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)

This function is a coroutine.

Sets permissions for the specified server role.

You must have manage_permissions to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

• role (ULIDOr[BaseRole]) – The role.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

• allow (Permissions) – The permissions to allow for the specified role.

• deny (Permissions) – The permissions to deny for the specified role.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  CannotGiveMissingPermissions	Your new provided permissions contained permissions you didn’t have.
  NotElevated	Rank of your top role is higher than rank of role you’re trying to set override for.
  MissingPermission	You do not have the proper permissions to edit permissions for this role.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/role was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The updated server with new permissions.

Return type:

Server

state

The state that controls this entity.

Type:

State

await subscribe()

This function is a coroutine.

Subscribes to this server.

await unban(user, *, http_overrides=None)

This function is a coroutine.

Unbans an user from the server.

You must have ban_members to do this.

Parameters:

• user (ULIDOr[BaseUser]) – The user to unban from the server.

• http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to unban members.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Category

Attributes

• channels
• default_permissions
• id
• role_permissions
• title

Methods

• def to_dict

class stoat.Category(id, title, channels, *, default_permissions=None, role_permissions=None)

Represents a category containing channels in Stoat server.

Parameters:

• id (str) – The category’s ID. Must be between 1 and 32 characters long.

• title (str) – The category’s title. Must be between 1 and 32 characters long.

• channels (List[str]) – The channel’s IDs inside this category.

• default_permissions (Optional[PermissionOverride]) –

  The default permissions in this category.

  Added in version 1.2.

• role_permissions (Optional[Dict[str, PermissionOverride]]) –

  The role permissions in this category.

  Added in version 1.2.

id

The category’s ID.

Type:

str

title

The category’s title.

Type:

str

default_permissions

The default permissions in this category.

Added in version 1.2.

Type:

Optional[PermissionOverride]

role_permissions

The role permissions in this category.

Added in version 1.2.

Type:

Dict[str, PermissionOverride]

channels

The channel’s IDs inside this category.

Type:

List[str]

to_dict()

dict: Convert category to raw data.

Attributes

• user_banned
• user_joined
• user_kicked
• user_left

Methods

• def to_dict

class stoat.SystemMessageChannels(*, user_joined=None, user_left=None, user_kicked=None, user_banned=None)

Represents system message channel assignments in a Stoat server.

user_joined

The channel’s ID to send user join messages in.

Type:

Optional[str]

user_left

The channel’s ID to send user left messages in.

Type:

Optional[str]

user_kicked

The channel’s ID to send user kicked messages in.

Type:

Optional[str]

user_banned

The channel’s ID to send user banned messages in.

Type:

Optional[str]

to_dict()

dict: Convert system message channels configuration to raw data.

Ban

Attributes

• reason
• server_id
• user
• user_id

Methods

• def to_dict

class stoat.Ban(*, server_id, user_id, reason, user)

Represents a server ban on Stoat.

server_id

The server’s ID.

Type:

str

user_id

The user’s ID that was banned.

Type:

str

reason

The ban’s reason.

Type:

Optional[str]

user

The user that was banned.

Type:

Optional[DisplayUser]

to_dict()

dict: Convert server ban to raw data.