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": {
"description": "The name of the guild (1-100 characters)",
"type": "string"
},
"icon": {
"description": "Base64-encoded image data for the guild icon",
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
]
},
"system_channel_id": {
"description": "The ID of the channel where system messages are sent",
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
]
},
"system_channel_flags": {
"$ref": "#/components/schemas/SystemChannelFlags",
"description": "Bitfield of system channel flags controlling which messages are suppressed"
},
"afk_channel_id": {
"description": "The ID of the AFK voice channel",
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
]
},
"afk_timeout": {
"type": "integer",
"minimum": 60,
"maximum": 3600,
"description": "AFK timeout in seconds (60-3600) before moving users to the AFK channel"
},
"default_message_notifications": {
"$ref": "#/components/schemas/DefaultMessageNotificationsInput"
},
"verification_level": {
"description": "Required verification level for members to participate",
"$ref": "#/components/schemas/GuildVerificationLevelInput"
},
"mfa_level": {
"$ref": "#/components/schemas/GuildMFALevelInput"
},
"nsfw_level": {
"$ref": "#/components/schemas/NSFWLevelInput",
"description": "Legacy: setting this translates to the modern nsfw flag and content warning level"
},
"nsfw": {
"description": "Whether the guild is marked as adult (18+) content",
"type": "boolean"
},
"content_warning_level": {
"$ref": "#/components/schemas/ContentWarningLevelInput",
"description": "Whether the guild displays a content warning before entering"
},
"content_warning_text": {
"description": "Custom guild-wide content warning text (max 200 characters); null falls back to a localized default",
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
},
"explicit_content_filter": {
"$ref": "#/components/schemas/GuildExplicitContentFilterInput"
},
"banner": {
"description": "Base64-encoded image data for the guild banner",
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
]
},
"splash": {
"description": "Base64-encoded image data for the guild splash screen",
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
]
},
"embed_splash": {
"description": "Base64-encoded image data for the embedded invite splash",
"anyOf": [
{
"$ref": "#/components/schemas/Base64ImageType"
},
{
"type": "null"
}
]
},
"splash_card_alignment": {
"description": "Alignment of the splash card (center, left, or right)",
"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"
],
"enum": [
0,
1,
2
],
"type": "integer"
},
"features": {
"maxItems": 100,
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildFeatureSchema"
},
"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": {
"description": "ISO8601 timestamp controlling how far back members without Read Message History can access messages. Set to null to disable historical access.",
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
},
"password": {
"description": "Account password for sudo verification",
"$ref": "#/components/schemas/PasswordType"
},
"mfa_method": {
"description": "MFA method to use for verification",
"x-enumNames": [
"TOTP",
"WebAuthn"
],
"x-enumDescriptions": [
"Time-based one-time password authentication via authenticator app",
"Security key or biometric authentication"
],
"enum": [
"totp",
"webauthn"
],
"type": "string"
},
"mfa_code": {
"description": "MFA verification code from an authenticator app",
"type": "string"
},
"webauthn_response": {
"description": "WebAuthn authentication response",
"$ref": "#/components/schemas/WebAuthnAuthenticationResponse"
},
"webauthn_challenge": {
"description": "WebAuthn challenge string",
"type": "string"
}
}
}Responses
200
Success
json
{
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for this guild",
"$ref": "#/components/schemas/SnowflakeStringType"
},
"name": {
"type": "string",
"description": "The name of the guild"
},
"icon": {
"description": "The hash of the guild icon",
"type": [
"string",
"null"
]
},
"banner": {
"description": "The hash of the guild banner",
"type": [
"string",
"null"
]
},
"banner_width": {
"description": "The width of the guild banner in pixels",
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
]
},
"banner_height": {
"description": "The height of the guild banner in pixels",
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
]
},
"splash": {
"description": "The hash of the guild splash screen",
"type": [
"string",
"null"
]
},
"splash_width": {
"description": "The width of the guild splash in pixels",
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
]
},
"splash_height": {
"description": "The height of the guild splash in pixels",
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
]
},
"splash_card_alignment": {
"description": "The alignment of the splash card",
"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"
],
"enum": [
0,
1,
2
],
"type": "integer"
},
"embed_splash": {
"description": "The hash of the embedded invite splash",
"type": [
"string",
"null"
]
},
"embed_splash_width": {
"description": "The width of the embedded invite splash in pixels",
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
]
},
"embed_splash_height": {
"description": "The height of the embedded invite splash in pixels",
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
]
},
"vanity_url_code": {
"description": "The vanity URL code for the guild",
"type": [
"string",
"null"
]
},
"owner_id": {
"description": "The ID of the guild owner",
"$ref": "#/components/schemas/SnowflakeStringType"
},
"system_channel_id": {
"description": "The ID of the channel where system messages are sent",
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeStringType"
},
{
"type": "null"
}
]
},
"system_channel_flags": {
"$ref": "#/components/schemas/SystemChannelFlags"
},
"rules_channel_id": {
"description": "The ID of the rules channel",
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeStringType"
},
{
"type": "null"
}
]
},
"afk_channel_id": {
"description": "The ID of the AFK voice channel",
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeStringType"
},
{
"type": "null"
}
]
},
"afk_timeout": {
"description": "AFK timeout in seconds before moving users to the AFK channel",
"$ref": "#/components/schemas/Int32Type"
},
"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"
},
"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": {
"description": "Custom guild-wide content warning text; null falls back to a localized default",
"type": [
"string",
"null"
]
},
"explicit_content_filter": {
"$ref": "#/components/schemas/GuildExplicitContentFilter"
},
"default_message_notifications": {
"$ref": "#/components/schemas/DefaultMessageNotifications"
},
"disabled_operations": {
"$ref": "#/components/schemas/GuildOperations"
},
"message_history_cutoff": {
"description": "ISO8601 timestamp controlling how far back members without Read Message History can access messages. When null, no historical access is allowed.",
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
},
"permissions": {
"description": "The current user permissions in this guild when available",
"$ref": "#/components/schemas/Permissions"
},
"roles": {
"description": "Roles in the guild from gateway state",
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildRoleResponse"
}
},
"emojis": {
"description": "Emojis in the guild from gateway state",
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildEmojiResponse"
}
},
"stickers": {
"description": "Stickers in the guild from gateway state",
"type": "array",
"items": {
"$ref": "#/components/schemas/GuildStickerResponse"
}
},
"channels": {
"description": "Channels visible to the requesting user from gateway state",
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelResponse"
}
},
"member_count": {
"description": "Total number of members in the guild",
"$ref": "#/components/schemas/Int32Type"
},
"online_count": {
"description": "Number of online members visible in the guild",
"$ref": "#/components/schemas/Int32Type"
},
"approximate_member_count": {
"description": "Approximate total member count (only when with_counts is true)",
"$ref": "#/components/schemas/Int32Type"
},
"approximate_presence_count": {
"description": "Approximate online member count (only when with_counts is true)",
"$ref": "#/components/schemas/Int32Type"
},
"threads_active": {
"type": "boolean",
"const": true,
"description": "Present and true when threads, forum and media channels are active in this guild for the requesting client. Only set on the current user guild list",
"x-fluxer-experiment": "channel_threads"
}
},
"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"
],
"additionalProperties": false
}400
Bad Request - The request was malformed or contained invalid data
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}401
Unauthorized - Authentication is required or the token is invalid
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}403
Forbidden - You do not have permission to perform this action
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}429
Too Many Requests - You are being rate limited
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
},
"retry_after": {
"type": "number",
"description": "Seconds to wait before retrying"
},
"global": {
"type": "boolean",
"description": "Whether this is a global rate limit"
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}500
Internal Server Error - An unexpected error occurred
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}