patch
/guilds/{guild_id}Update guild settings
Requires manage_guild permission. Updates guild name, description, icon, banner, and other configuration options.
update_guild
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| guild_id* | path | SnowflakeType | The ID of the guild |
Request body
application/json
json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the guild (1-100 characters)"
},
"icon": {
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
],
"description": "Base64-encoded image data for the guild icon"
},
"system_channel_id": {
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
],
"description": "The ID of the channel where system messages are sent"
},
"system_channel_flags": {
"$ref": "#/components/schemas/SystemChannelFlags"
},
"afk_channel_id": {
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
],
"description": "The ID of the AFK voice channel"
},
"afk_timeout": {
"type": "integer",
"minimum": 60,
"maximum": 3600,
"format": "int32",
"description": "AFK timeout in seconds (60-3600) before moving users to the AFK channel"
},
"default_message_notifications": {
"$ref": "#/components/schemas/DefaultMessageNotifications",
"description": "Default notification level for new members"
},
"verification_level": {
"$ref": "#/components/schemas/GuildVerificationLevel",
"description": "Required verification level for members to participate"
},
"mfa_level": {
"$ref": "#/components/schemas/GuildMFALevel",
"description": "Required MFA level for moderation actions"
},
"nsfw_level": {
"$ref": "#/components/schemas/NSFWLevel",
"description": "Legacy: setting this translates to the modern nsfw flag and content warning level"
},
"nsfw": {
"type": "boolean",
"description": "Whether the guild is marked as adult (18+) content"
},
"content_warning_level": {
"$ref": "#/components/schemas/ContentWarningLevel",
"description": "Whether the guild displays a content warning before entering"
},
"content_warning_text": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Custom guild-wide content warning text (max 200 characters); null falls back to a localized default"
},
"explicit_content_filter": {
"$ref": "#/components/schemas/GuildExplicitContentFilter",
"description": "Level of content filtering for explicit media"
},
"banner": {
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
],
"description": "Base64-encoded image data for the guild banner"
},
"splash": {
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
],
"description": "Base64-encoded image data for the guild splash screen"
},
"embed_splash": {
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
],
"description": "Base64-encoded image data for the embedded invite splash"
},
"splash_card_alignment": {
"type": "integer",
"enum": [
0,
1,
2
],
"x-enumNames": [
"CENTER",
"LEFT",
"RIGHT"
],
"x-enumDescriptions": [
"Splash card is centred",
"Splash card is aligned to the left",
"Splash card is aligned to the right"
],
"description": "Alignment of the splash card (center, left, or right)"
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildFeatureSchema"
},
"maxItems": 100,
"description": "Complete desired feature set for the guild. Only user-toggleable features may differ from the current set; non-toggleable features must be preserved as-is."
},
"message_history_cutoff": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp controlling how far back members without Read Message History can access messages. Set to null to disable historical access."
},
"password": {
"$ref": "#/components/schemas/PasswordType"
},
"mfa_method": {
"type": "string",
"enum": [
"totp",
"webauthn"
],
"x-enumNames": [
"TOTP",
"WebAuthn"
],
"x-enumDescriptions": [
"Time-based one-time password authentication via authenticator app",
"Security key or biometric authentication"
],
"description": "MFA method to use for verification"
},
"mfa_code": {
"type": "string",
"description": "MFA verification code from an authenticator app"
},
"webauthn_response": {
"type": "object",
"description": "WebAuthn authentication response"
},
"webauthn_challenge": {
"type": "string",
"description": "WebAuthn challenge string"
}
}
}Responses
200
Success
json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"description": "The unique identifier for this guild"
},
"name": {
"type": "string",
"description": "The name of the guild"
},
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The hash of the guild icon"
},
"banner": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The hash of the guild banner"
},
"banner_width": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The width of the guild banner in pixels"
},
"banner_height": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The height of the guild banner in pixels"
},
"splash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The hash of the guild splash screen"
},
"splash_width": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The width of the guild splash in pixels"
},
"splash_height": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The height of the guild splash in pixels"
},
"splash_card_alignment": {
"type": "integer",
"enum": [
0,
1,
2
],
"description": "The alignment of the splash card"
},
"embed_splash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The hash of the embedded invite splash"
},
"embed_splash_width": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The width of the embedded invite splash in pixels"
},
"embed_splash_height": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The height of the embedded invite splash in pixels"
},
"vanity_url_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The vanity URL code for the guild"
},
"owner_id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"description": "The ID of the guild owner"
},
"system_channel_id": {
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
],
"description": "The ID of the channel where system messages are sent"
},
"system_channel_flags": {
"$ref": "#/components/schemas/SystemChannelFlags"
},
"rules_channel_id": {
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
],
"description": "The ID of the rules channel"
},
"afk_channel_id": {
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
],
"description": "The ID of the AFK voice channel"
},
"afk_timeout": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"format": "int32",
"description": "AFK timeout in seconds before moving users to the AFK channel"
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildFeatureSchema"
},
"description": "Array of guild feature flags"
},
"verification_level": {
"$ref": "#/components/schemas/GuildVerificationLevel",
"description": "Required verification level for members to participate"
},
"mfa_level": {
"$ref": "#/components/schemas/GuildMFALevel",
"description": "Required MFA level for moderation actions"
},
"nsfw_level": {
"$ref": "#/components/schemas/NSFWLevel",
"description": "The NSFW level of the guild (legacy; derived from nsfw)"
},
"nsfw": {
"type": "boolean",
"description": "Whether the guild is marked as adult (18+) content"
},
"content_warning_level": {
"$ref": "#/components/schemas/ContentWarningLevel",
"description": "Whether the guild displays a content warning before entering"
},
"content_warning_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Custom guild-wide content warning text; null falls back to a localized default"
},
"explicit_content_filter": {
"$ref": "#/components/schemas/GuildExplicitContentFilter",
"description": "Level of content filtering for explicit media"
},
"default_message_notifications": {
"$ref": "#/components/schemas/DefaultMessageNotifications",
"description": "Default notification level for new members"
},
"disabled_operations": {
"$ref": "#/components/schemas/GuildOperations"
},
"message_history_cutoff": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp controlling how far back members without Read Message History can access messages. When null, no historical access is allowed."
},
"permissions": {
"type": "string",
"format": "int64",
"pattern": "^[0-9]+$",
"description": "The current user permissions in this guild when available"
},
"roles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildRoleResponse"
},
"description": "Roles in the guild from gateway state"
},
"emojis": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildEmojiResponse"
},
"description": "Emojis in the guild from gateway state"
},
"stickers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildStickerResponse"
},
"description": "Stickers in the guild from gateway state"
},
"channels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelResponse"
},
"description": "Channels visible to the requesting user from gateway state"
},
"member_count": {
"$ref": "#/components/schemas/Int32Type"
},
"online_count": {
"$ref": "#/components/schemas/Int32Type"
},
"approximate_member_count": {
"$ref": "#/components/schemas/Int32Type"
},
"approximate_presence_count": {
"$ref": "#/components/schemas/Int32Type"
}
},
"required": [
"id",
"name",
"splash_card_alignment",
"owner_id",
"system_channel_flags",
"afk_timeout",
"features",
"verification_level",
"mfa_level",
"nsfw_level",
"nsfw",
"content_warning_level",
"explicit_content_filter",
"default_message_notifications",
"disabled_operations"
]
}400
Bad Request - The request was malformed or contained invalid data
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}401
Unauthorized - Authentication is required or the token is invalid
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}403
Forbidden - You do not have permission to perform this action
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}429
Too Many Requests - You are being rate limited
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RATE_LIMITED"
]
},
"message": {
"type": "string"
},
"retry_after": {
"type": "number",
"description": "Seconds to wait before retrying"
},
"global": {
"type": "boolean",
"description": "Whether this is a global rate limit"
}
},
"required": [
"code",
"message",
"retry_after"
]
}500
Internal Server Error - An unexpected error occurred
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}