astrae

API reference

Protocol types

The integers and flags Discord puts on the wire. Member lists below are what Astrae knows. Discord can add values first; ChannelType keeps an unknown int as UNKNOWN_<n> instead of exploding.

Name Purpose
Catalog Field-level model behavior.
docs_for(User) / User.docs Discord's own page for a type.
astrae.core.DOCS Same URL map.
from astrae import Intents
from astrae.core import docs_for

docs_for(Intents)
# https://discord.com/developers/docs/events/gateway#gateway-intents

Application commands and interactions

ApplicationCommandType

Member Value Meaning
CHAT_INPUT 1 Slash command.
USER 2 User context-menu command.
MESSAGE 3 Message context-menu command.

ApplicationCommandOptionType

Member Value Astrae option class
SUB_COMMAND 1 Nested command, not an option descriptor.
SUB_COMMAND_GROUP 2 Nested group, not an option descriptor.
STRING 3 StringOption
INTEGER 4 IntegerOption
BOOLEAN 5 BooleanOption
USER 6 UserOption
CHANNEL 7 ChannelOption
ROLE 8 RoleOption
MENTIONABLE 9 MentionableOption
NUMBER 10 NumberOption
ATTACHMENT 11 AttachmentOption

InteractionType

Member Value Meaning
PING 1 HTTP interaction handshake.
APPLICATION_COMMAND 2 Slash or context-menu invoke.
MESSAGE_COMPONENT 3 Button or select.
APPLICATION_COMMAND_AUTOCOMPLETE 4 Option autocomplete.
MODAL_SUBMIT 5 Modal submit.

InteractionCallbackType

Member Value Meaning
PONG 1 Acknowledge a ping.
CHANNEL_MESSAGE_WITH_SOURCE 4 Reply with a message.
DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE 5 Defer a command reply.
DEFERRED_UPDATE_MESSAGE 6 Defer a component update.
UPDATE_MESSAGE 7 Edit the source message.
APPLICATION_COMMAND_AUTOCOMPLETE_RESULT 8 Autocomplete choices.
MODAL 9 Open a modal.
Name Purpose
Callback 2 / 3 Unused. Newer Discord callback types show up here when Astrae adds them.

Components

ComponentType

Member Value Builder
ACTION_ROW 1 ActionRow
BUTTON 2 Button
STRING_SELECT 3 SelectMenu
TEXT_INPUT 4 TextInput
USER_SELECT 5 SelectMenu(kind=...)
ROLE_SELECT 6 SelectMenu(kind=...)
MENTIONABLE_SELECT 7 SelectMenu(kind=...)
CHANNEL_SELECT 8 SelectMenu(kind=...)
SECTION 9 Section
TEXT_DISPLAY 10 TextDisplay
THUMBNAIL 11 Thumbnail
MEDIA_GALLERY 12 MediaGallery
FILE 13 File
SEPARATOR 14 Separator
CONTAINER 17 Container
LABEL 18 No builder yet.
FILE_UPLOAD 19 No builder yet.
Name Purpose
V2 + legacy children Discord rejects the mix.
COMPONENTS_V2_FLAG MessageFlags.IS_COMPONENTS_V2.

ButtonStyle

Member Value Meaning
PRIMARY 1 Blurple. Requires custom_id.
SECONDARY 2 Grey. Requires custom_id.
SUCCESS 3 Green. Requires custom_id.
DANGER 4 Red. Requires custom_id.
LINK 5 URL button. Requires url, not custom_id.
PREMIUM 6 SKU button.

Channels

ChannelType

Member Value Meaning
GUILD_TEXT / text 0 Guild text channel.
DM 1 Direct message.
GUILD_VOICE / voice 2 Guild voice channel.
GROUP_DM 3 Group DM.
GUILD_CATEGORY / category 4 Category.
GUILD_ANNOUNCEMENT 5 Announcement channel.
ANNOUNCEMENT_THREAD 10 Thread in an announcement channel.
PUBLIC_THREAD 11 Public thread.
PRIVATE_THREAD 12 Private thread.
GUILD_STAGE_VOICE 13 Stage channel.
GUILD_DIRECTORY 14 Hub directory.
GUILD_FORUM 15 Forum.
GUILD_MEDIA 16 Media channel.
Name Purpose
Lowercase aliases discord.py names (text, voice, category).
Unknown ints Kept as UNKNOWN_<n>.

Message flags

MessageFlags is an IntFlag. Combine members with |. IS_COMPONENTS_V2 is also COMPONENTS_V2_FLAG.

Member Bit Meaning
CROSSPOSTED 0 Announcement message was published.
IS_CROSSPOST 1 Message originated as a crosspost.
SUPPRESS_EMBEDS 2 Do not render embeds.
SOURCE_MESSAGE_DELETED 3 Source of a crosspost was deleted.
URGENT 4 Urgent message.
HAS_THREAD 5 Message has a thread.
EPHEMERAL 6 Only the invoking user sees it.
LOADING 7 Deferred interaction placeholder.
FAILED_TO_MENTION_SOME_ROLES_IN_THREAD 8 Role mention failed in a thread.
SUPPRESS_NOTIFICATIONS 12 Silent message.
IS_VOICE_MESSAGE 13 Voice message.
IS_COMPONENTS_V2 15 Components V2 layout. Also COMPONENTS_V2_FLAG.

Permissions

Permission is the bit mask.

Name Purpose
permissions_from / channel_permissions Only see the models you pass.
Role position Not a bit.
Member Bit
CREATE_INSTANT_INVITE 0
KICK_MEMBERS 1
BAN_MEMBERS 2
ADMINISTRATOR 3
MANAGE_CHANNELS 4
MANAGE_GUILD 5
ADD_REACTIONS 6
VIEW_AUDIT_LOG 7
PRIORITY_SPEAKER 8
STREAM 9
VIEW_CHANNEL 10
SEND_MESSAGES 11
SEND_TTS_MESSAGES 12
MANAGE_MESSAGES 13
EMBED_LINKS 14
ATTACH_FILES 15
READ_MESSAGE_HISTORY 16
MENTION_EVERYONE 17
USE_EXTERNAL_EMOJIS 18
VIEW_GUILD_INSIGHTS 19
CONNECT 20
SPEAK 21
MUTE_MEMBERS 22
DEAFEN_MEMBERS 23
MOVE_MEMBERS 24
USE_VAD 25
CHANGE_NICKNAME 26
MANAGE_NICKNAMES 27
MANAGE_ROLES 28
MANAGE_WEBHOOKS 29
MANAGE_GUILD_EXPRESSIONS 30
USE_APPLICATION_COMMANDS 31
REQUEST_TO_SPEAK 32
MANAGE_EVENTS 33
MANAGE_THREADS 34
CREATE_PUBLIC_THREADS 35
CREATE_PRIVATE_THREADS 36
USE_EXTERNAL_STICKERS 37
SEND_MESSAGES_IN_THREADS 38
USE_EMBEDDED_ACTIVITIES 39
MODERATE_MEMBERS 40
VIEW_CREATOR_MONETIZATION_ANALYTICS 41
USE_SOUNDBOARD 42
CREATE_GUILD_EXPRESSIONS 43
CREATE_EVENTS 44
USE_EXTERNAL_SOUNDS 45
SEND_VOICE_MESSAGES 46
SEND_POLLS 49
USE_EXTERNAL_APPS 50
Name Purpose
Role.is_dangerous True when the role includes kick, ban, administrator, manage guild/roles/channels/messages/webhooks/expressions/threads, mention everyone, or timeout members.

Gateway intents

An intent is not a permission.

Name Purpose
Privileged GUILD_MEMBERS, GUILD_PRESENCES, MESSAGE_CONTENT. Portal, then the client, then Discord if they want a review.
Intents(members=True, message_content=True) Keyword constructor. Unknown names raise TypeError.
Member Bit Privileged
GUILDS 0 No
GUILD_MEMBERS 1 Yes
GUILD_MODERATION 2 No
GUILD_EXPRESSIONS 3 No
GUILD_INTEGRATIONS 4 No
GUILD_WEBHOOKS 5 No
GUILD_INVITES 6 No
GUILD_VOICE_STATES 7 No
GUILD_PRESENCES 8 Yes
GUILD_MESSAGES 9 No
GUILD_MESSAGE_REACTIONS 10 No
GUILD_MESSAGE_TYPING 11 No
DIRECT_MESSAGES 12 No
DIRECT_MESSAGE_REACTIONS 13 No
DIRECT_MESSAGE_TYPING 14 No
MESSAGE_CONTENT 15 Yes
GUILD_SCHEDULED_EVENTS 16 No
AUTO_MODERATION_CONFIGURATION 20 No
AUTO_MODERATION_EXECUTION 21 No
GUILD_MESSAGE_POLLS 24 No
DIRECT_MESSAGE_POLLS 25 No

Composite values:

Member Meaning
NONE Empty mask.
UNPRIVILEGED Every non-privileged intent Astrae defines.
ALL UNPRIVILEGED plus the three privileged intents.
DEFAULT GUILDS \| GUILD_MESSAGES \| MESSAGE_CONTENT \| DIRECT_MESSAGES.
Name Purpose
Client default Intents.DEFAULT when you omit intents.

Presence

from astrae import Status, Activity, ActivityType.

Status

Member Wire value
ONLINE online
IDLE idle
DO_NOT_DISTURB / DND dnd
INVISIBLE invisible
OFFLINE offline

ActivityType

Member Value Meaning
PLAYING / playing 0 Playing
STREAMING / streaming 1 Streaming; Activity.url is used
LISTENING / listening 2 Listening
WATCHING / watching 3 Watching
CUSTOM / custom 4 Custom status
COMPETING / competing 5 Competing

Activity

Activity(name: str, type: ActivityType = ActivityType.PLAYING, url: str | None = None)
Name Purpose
to_dict() Discord activity payload (name, type, url when set). Pass to Client.change_presence(activity=...).

IDs, time, and omitted fields

Name Purpose
Snowflake Models with an id. created_at is the timestamp in the ID.
SnowflakeTime That UTC datetime. .timestamp is Unix seconds.
created_at(id) / created_at_ms(id) Decode a raw snowflake.
UNSET Leave the key out. None is JSON null.
omit_unset / dump_unset / is_set Partial updates.

Event value types

What listeners get. Not REST resources.

Type Discord object
EventContext Astrae delivery metadata (name, shard, before, raw).
Update Pair of before / after for update events.
VoiceState Voice state
ReactionEvent Message reaction add
AuditLogEntry Audit log entry
MembersChunk Guild members chunk
ShardEvent Astrae shard lifecycle (shard_disconnect, shard_reconnect, shard_ready).

Models

A payload. Fields can be missing. Mutating it does not update Discord.

Name Purpose
Catalog Accessors.
Collection Astrae list, not a Discord object.
Type Discord object
User, ClientUser User
Member Guild member
Guild Guild
Role Role
Channel Channel
PermissionOverwrite Overwrite
Emoji Emoji
Sticker Sticker
StickerItem Sticker item
Message Message
Attachment Attachment
Embed, EmbedField, EmbedAuthor, EmbedFooter, EmbedMedia Embed
Reaction Reaction
MessageComponent Component
Interaction, InteractionData Interaction
CommandOptionValue Command option
Resolved Resolved data
ReadyEvent Ready
Asset Image formatting

Payload builders

JSON you send. Discord still validates it.

Type Discord object
Embed, EmbedField Embed
AllowedMentions Allowed mentions
Poll Poll create
PollAnswer Poll media
ActionRow Action row
Button Button
SelectMenu String select
SelectOption Select option
TextInput Text input
Container Container
Section Section
TextDisplay Text display
Thumbnail Thumbnail
MediaGallery, MediaGalleryItem Media gallery
Separator Separator
File File