Skip to main content

Guild Resource

Guilds represent communities or servers where users can interact through channels. Each guild has customizable settings, roles, and features.

Guild Object

Structure

id
Snowflake
required
Unique guild identifier
owner_id
Snowflake
required
User ID of the guild owner
name
string
required
Guild name (2-100 characters)
vanity_url_code
string | null
Custom vanity URL code (requires VANITY_URL feature)
icon_hash
string | null
Hash of the guild’s icon image
banner_hash
string | null
Hash of the guild’s banner image
banner_width
integer | null
Banner image width in pixels
banner_height
integer | null
Banner image height in pixels
splash_hash
string | null
Hash of the guild’s invite splash image
splash_card_alignment
integer
default:"0"
Alignment of splash card: 0 (center), 1 (left), 2 (right)
features
array of strings
Enabled guild features (see Guild Features)
verification_level
integer
default:"0"
Required verification level for members (see Verification Levels)
mfa_level
integer
default:"0"
Required MFA level for moderators: 0 (none), 1 (elevated)
nsfw_level
integer
default:"0"
Guild NSFW classification (see NSFW Levels)
explicit_content_filter
integer
default:"0"
Explicit content filter level (see Content Filter)
default_message_notifications
integer
default:"0"
Default notification level: 0 (all messages), 1 (only mentions)
system_channel_id
Snowflake | null
Channel for system messages (welcome, boosts)
system_channel_flags
integer
default:"0"
Bitfield of system channel settings
rules_channel_id
Snowflake | null
Channel containing guild rules
afk_channel_id
Snowflake | null
Voice channel for idle members
afk_timeout
integer
default:"0"
Seconds of inactivity before moving to AFK channel
member_count
integer
default:"0"
Total number of members in the guild
version
integer
required
Version number for optimistic concurrency control

Example Guild

{
  "id": "987654321098765432",
  "owner_id": "123456789012345678",
  "name": "Fluxer Community",
  "vanity_url_code": "fluxer",
  "icon_hash": "a1b2c3d4e5f6",
  "banner_hash": "b2c3d4e5f6a7",
  "banner_width": 1920,
  "banner_height": 1080,
  "splash_hash": null,
  "splash_card_alignment": 0,
  "features": [
    "VANITY_URL",
    "BANNER",
    "ANIMATED_ICON",
    "DISCOVERABLE"
  ],
  "verification_level": 2,
  "mfa_level": 1,
  "nsfw_level": 0,
  "explicit_content_filter": 2,
  "default_message_notifications": 1,
  "system_channel_id": "111222333444555666",
  "system_channel_flags": 0,
  "rules_channel_id": "222333444555666777",
  "afk_channel_id": "333444555666777888",
  "afk_timeout": 300,
  "member_count": 12450,
  "version": 42
}

Guild Features

Guilds can have various features enabled based on premium status or partnerships.

Verification Levels

NSFW Levels

Content Filter

System Channel Flags

Endpoints

Create Guild

POST /api/v1/guilds
Create a new guild.
name
string
required
Guild name (2-100 characters)
icon
string
Base64 encoded image data

Get Guild

GET /api/v1/guilds/{guild_id}
Returns guild information.
with_counts
boolean
Include approximate member and presence counts

Modify Guild

PATCH /api/v1/guilds/{guild_id}
Update guild settings. Requires MANAGE_GUILD permission.
name
string
New guild name
icon
string | null
New icon (base64 encoded) or null to remove
banner
string | null
New banner (base64 encoded) or null to remove
verification_level
integer
New verification level
default_message_notifications
integer
New default notification level
explicit_content_filter
integer
New content filter level
afk_channel_id
Snowflake | null
New AFK channel
afk_timeout
integer
New AFK timeout in seconds
system_channel_id
Snowflake | null
New system messages channel
rules_channel_id
Snowflake | null
New rules channel

Delete Guild

DELETE /api/v1/guilds/{guild_id}
Delete the guild. Requires guild ownership.

Get Guild Channels

GET /api/v1/guilds/{guild_id}/channels
Returns all channels in the guild.

Get Guild Members

GET /api/v1/guilds/{guild_id}/members
Returns guild members.
limit
integer
default:"100"
Max members to return (1-1000)
after
Snowflake
Get members after this user ID

Build docs developers (and LLMs) love