Admin guilds

Admin guild operations read and change the guilds the public Guilds resource exposes. Most of them need no membership in the guild and no guild permission, and Remove guild member and Ban guild member are the two exceptions.

Archives owns the archive lifecycle and the downloads.

Reads use the admin:lookup bucket, which permits 200 requests per minute for each authenticated user. Writes use the admin:guild:modify bucket, which permits 100 requests per minute for each authenticated user. Create guild archive is the one write served from the read bucket.

Guild deletion is immediate

Delete guild destroys the guild at once. There is no scheduled deletion, no recovery window, and no restore operation.

Admin guild object

The compact guild representation returned by List guilds and by List user guilds. It has no channel or role state.

Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild
features	array[string]	The complete guild feature set (at most 100)
owner_id	snowflake	The ID of the owner
owner_username1	?string	The username of the owner
owner_global_name1	?string	The display name of the owner
owner_discriminator1	?string	The owner discriminator, zero-padded to four digits
icon	?string	The icon hash, or null when unset
banner	?string	The banner hash, or null when unset
member_count2	integer	The recorded member count
nsfw_level?	integer	The NSFW level
nsfw?3	boolean	Whether the guild is flagged as adult content
content_warning_level?3	integer	The guild content warning level
content_warning_text?3	?string	The custom content warning text
approximate_member_count?4	integer	The member count the main Gateway reports
approximate_presence_count?4	integer	The connected member count the main Gateway reports

¹ All three are null whenever the owner account is not resolved. List guilds never resolves it, so all three are always null there

² A member connecting or disconnecting does not change it

³ No operation populates these three, so they are absent from every current response

⁴ Present only on List user guilds when that operation is asked for counts

Example

{
  "id": "1471002884199612416",
  "name": "Tidepool",
  "features": ["DISCOVERABLE", "VANITY_URL"],
  "owner_id": "1483920011884392448",
  "owner_username": null,
  "owner_global_name": null,
  "owner_discriminator": null,
  "icon": "b7f1c2d3e4a5968778695a4b3c2d1e0f",
  "banner": null,
  "member_count": 4182,
  "nsfw_level": 0
}

Admin guild detail object

The full guild representation returned by Get guild. It embeds every channel and every role of the guild.

Structure

Field	Type	Description
id	snowflake	The ID of the guild
owner_id	snowflake	The ID of the owner
owner_username1	?string	The username of the owner
owner_global_name1	?string	The display name of the owner
owner_discriminator1	?string	The owner discriminator, zero-padded to four digits
name	string	The name of the guild (1-100 characters)
vanity_url_code	?string	The custom invite code, or null when the guild owns none
icon	?string	The icon hash, or null when unset
banner	?string	The banner hash, or null when unset
splash	?string	The invite splash hash, or null when unset
embed_splash	?string	The embedded invite splash hash, or null when unset
features	array[string]	The complete guild feature set (at most 100)
verification_level	integer	The verification level
mfa_level	integer	The MFA level required of moderators
nsfw_level	integer	The NSFW level
nsfw?2	boolean	Whether the guild is flagged as adult content
content_warning_level?2	integer	The guild content warning level
content_warning_text?2	?string	The custom content warning text
explicit_content_filter	integer	The explicit content filter level
default_message_notifications	integer	The default message notification level
afk_channel_id	?snowflake	The voice channel idle members are moved to, or null when unset
afk_timeout	integer	The idle time before a member is moved, in seconds
system_channel_id	?snowflake	The channel system messages are sent to, or null when they are disabled
system_channel_flags	integer	The system channel flags
rules_channel_id	?snowflake	The channel holding the guild rules, or null when unset
disabled_operations	integer	The disabled guild operations bitfield
member_count	integer	The recorded member count
channels	array[Admin guild channel object]	Every channel in the guild
roles	array[Admin guild role object]	Every role in the guild

¹ All three are null when the owner account cannot be resolved

² The operation does not populate these three, so they are absent from every current response

Admin guild channel object

Structure

Field	Type	Description
id	snowflake	The ID of the channel
name	?string	The channel name (1-100 characters)
type	integer	The channel type
position	integer	The sort position within the guild
parent_id	?snowflake	The parent category ID, or null when the channel is top-level
nsfw	?boolean	Whether the channel is marked age restricted
nsfw_override?3	?boolean	The age restriction set on the channel itself
content_warning_level?3	integer	The content warning level set on the channel
content_warning_text?3	?string	The content warning text set on the channel
url4	?string	The external channel URL (1-2048 characters)

³ The operation does not populate these three, so they are absent from every current response

⁴ Null for every channel type that is not an external link channel

Admin guild role object

Structure

Field	Type	Description
id	snowflake	The ID of the role
name	string	The role name (1-100 characters)
color	integer	The packed RGB colour
position	integer	The sort position within the guild
permissions	string	The permission bitfield as an unsigned 64-bit decimal string
hoist	boolean	Whether the role is displayed separately in the member list
mentionable	boolean	Whether the role can be mentioned by anyone

Admin guild update object

The guild state Update guild reads back after applying the request. It has no channel, role, or owner identity state.

Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild (1-100 characters)
features	array[string]	The complete guild feature set after the update (at most 100)
owner_id	snowflake	The ID of the owner after the update
icon	?string	The icon hash, or null when unset or cleared
banner	?string	The banner hash, or null when unset or cleared
member_count	integer	The recorded member count
nsfw_level	integer	The NSFW level

Admin guild expression object

One custom emoji or one sticker of a guild, together with a resolvable media URL. The two listings return the same shape.

Structure

Field	Type	Description
id	snowflake	The ID of the emoji or sticker
name	string	The expression name (1-100 characters)
animated	boolean	Whether the stored image is animated
creator_id	snowflake	The account that uploaded the expression
media_url1	string	The Media Proxy URL the expression is served from (1-2048 characters)

¹ Always the WebP representation, at size 160 for an emoji and size 320 for a sticker, and it has the animated=true selector only when animated is true

Example

{
  "id": "1496613881730531328",
  "name": "party_parrot",
  "animated": true,
  "creator_id": "1483920011884392448",
  "media_url": "https://media.example.com/emojis/1496613881730531328.webp?size=160&animated=true"
}

Admin guild asset purge result object

One entry of the processed array returned by Purge guild assets.

Structure

Field	Type	Description
id	snowflake	The asset that was purged
asset_type	string	The asset type the ID resolved to
found_in_db1	boolean	Whether the ID matched an emoji or sticker record
guild_id2	?snowflake	The guild the purged record belonged to
guild_nsfw_level2	?integer	The NSFW level of that guild

¹ False exactly when asset_type is unknown, in which case only the stored media was queued for removal

² Both null when asset_type is unknown, and guild_nsfw_level is also null when the owning guild can no longer be resolved

Admin guild asset purge error object

One entry of the errors array returned by Purge guild assets.

Structure

Field	Type	Description
id	string	The asset that could not be purged, as supplied
error1	string	The reason the asset could not be purged (1-4000 characters)

¹ The operation produces Invalid numeric ID, Asset belongs to another guild, and Failed to purge asset. Any other value is the message of the underlying failure

Asset types

Value	Description
emoji	The ID resolved to a custom emoji owned by the requested guild
sticker	The ID resolved to a sticker owned by the requested guild
unknown	The ID matched no emoji and no sticker record, and only associated media was queued for removal

An ID owned by a different guild appears in errors with no asset type.

List guilds

GET/v1/admin/guilds

Searches guilds through the guild search index and returns Admin guild objects. Requires guild:lookup.

The index matches q against the guild name, the discovery tags, the custom invite code, and the discovery description, in that order of weight. Hits are ordered by guild creation time ascending, so the oldest matching guild is first. An empty or omitted q matches every indexed guild.

Query parameters

Field	Type	Description
q?1	string	Free-text query (1-1024 characters)
limit?	integer	Maximum guilds to return (1-200, default 50)
offset?	integer	Guilds to skip before returning results (0-10000, default 0)

¹ A q of all decimal digits also resolves that value as an exact guild ID, but only while offset is 0. A guild the index did not return is prepended to guilds and adds one to total

Response body

Field	Type	Description
guilds	array[Admin guild object]	Guilds in this page
total2	integer	The number of guilds the index reported for the query

² The value can exceed the number of entries in guilds. Pagination advances with offset, and the operation returns no cursor

Response

Status	Body	Condition
200	response body	Guild page was returned
403	error response	FEATURE_TEMPORARILY_DISABLED, because the instance has no search backend configured

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Get guild

GET/v1/admin/guilds/{guild_id}

Returns one guild with its channels and roles. Requires guild:lookup.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response body

Field	Type	Description
guild1	?Admin guild detail object	The guild, or null when the ID resolves to nothing

¹ A guild that does not exist answers 200 with a null guild

Response

Status	Body	Condition
200	response body	A lookup was performed, whether or not it resolved

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Update guild

PATCH/v1/admin/guilds/{guild_id}Audit reason

Applies one or more field groups to a guild and returns the Admin guild update object read back afterwards. Omitted fields are left unchanged.

This is the only way to change the owner of a guild without acting as its current owner. The public Transfer guild ownership operation requires the caller to be the owner.

Fluxer evaluates authorisation in two stages and reads the body between them. The account first needs at least one of guild:update:name, guild:update:settings, guild:update:features, guild:update:vanity, and guild:transfer_ownership. The validated body then selects a set of ACLs and every one of them is required, so a body with name and nsfw needs both guild:update:name and guild:update:settings. The wildcard satisfies both stages.

• guild:update:name is selected by name.
• guild:update:settings is selected by fields, verification_level, mfa_level, nsfw_level, nsfw, content_warning_level, content_warning_text, explicit_content_filter, default_message_notifications, and disabled_operations.
• guild:update:features is selected by add_features and remove_features.
• guild:update:vanity is selected by vanity_url_code.
• guild:transfer_ownership is selected by new_owner_id.

A body with no field at all selects nothing, so an empty patch applies no change.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

Field	Type	Description
name?	string	The replacement name (1-100 characters)
vanity_url_code?1	?string	The replacement custom invite code, or null to release the current one
new_owner_id?2	snowflake	The replacement owner
add_features?3	array[string]	Guild features to add (at most 100)
remove_features?3	array[string]	Guild features to remove (at most 100)
fields?4	array[string]	Image fields to clear, each icon, banner, splash, or embed_splash (at most 10)
verification_level?	integer	The replacement verification level
mfa_level?	integer	The replacement MFA level
nsfw_level?	integer	The replacement NSFW level
nsfw?5	boolean	Accepted and ignored
content_warning_level?5	integer	Accepted and ignored
content_warning_text?5	?string	Accepted and ignored (at most 200 characters)
explicit_content_filter?	integer	The replacement explicit content filter level
default_message_notifications?	integer	The replacement default message notification level
disabled_operations?6	integer	The replacement disabled guild operations bitfield

¹ Normalised to lowercase with whitespace folded to hyphens and consecutive hyphens collapsed. The normalised result is 2 to 32 characters, and a shorter or longer one is rejected with 400

² The operation does not confirm that the replacement account exists, and an unresolvable owner makes every owner_ field null on later reads

³ Additions are applied before removals, so a feature named in both is removed. Any string is accepted

⁴ The array only clears an image, and no Admin operation uploads one

⁵ Validated, selects guild:update:settings, and records an update_settings audit entry. The guild record is left unchanged

⁶ Any integer from 0 to 2147483647, stored as supplied, including bits outside the documented registry

A code already claimed by any invite is rejected with 400 INVALID_FORM_BODY and the validation code THIS_VANITY_URL_IS_ALREADY_TAKEN against vanity_url_code.

The channel references, idle timeout, and message history cutoff of a guild are not Admin-writable. They change through the public Modify guild operation.

Response body

Field	Type	Description
guild	Admin guild update object	The guild state read back after the request was applied

Response

Status	Body	Condition
200	response body	Every selected field group was applied
400	error response	The custom invite code is malformed or already claimed
403	error response	MISSING_ACL, because the account holds none of the five update ACLs, or lacks an ACL a supplied field selects
404	error response	UNKNOWN_GUILD, because the guild does not exist

Field groups apply one at a time

The groups run in a fixed order: image clears, settings, features, name, custom invite code, ownership. Each is a separate write with its own Guild Update Dispatch and its own Admin audit entry. A failure part way through leaves the earlier groups applied.

Side effects

Clearing an image field queues the previous stored object for deletion. Replacing the custom invite code deletes the invite record holding the previous code and creates one for the new code, while sending null deletes the previous record without creating another.

Supplying add_features or remove_features reconciles an existing discovery application. The application is approved when DISCOVERABLE becomes present and it is not already approved, and it is marked removed when DISCOVERABLE becomes absent and it was approved. A guild that has never applied for discovery gains no application.

Every applied group refreshes the guild’s entry in the guild search index and fires one Guild Update Dispatch to every session that can see the guild, including when the write changes no value.

Each applied group records one Admin audit entry with the target type guild and the guild ID as the target. The actions are clear_fields with the cleared field names, update_settings with each applied setting, and update_features with the added, removed, and resulting feature sets. The remaining actions are update_name with the old and new names, update_vanity with the old and new codes, and transfer_ownership with the old and new owner IDs.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Delete guild

DELETE/v1/admin/guilds/{guild_id}Audit reason

Permanently deletes a guild and every record it owns. Requires guild:delete.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response body

Field	Type	Description
success	boolean	Always true

Response

Status	Body	Condition
200	response body	Guild was deleted
404	error response	UNKNOWN_GUILD, because the guild does not exist

A guild archive is the only way back

The guild, its channels, roles, memberships, messages, and attachments are destroyed as soon as the request is accepted. Take a guild archive first when the content has to be retained.

Side effects

Fluxer emits one Guild Delete Dispatch first, then detaches every member from the guild on the main Gateway. It deletes each member’s guild settings entry for the guild, and drops each human member’s guild folder references to the guild.

Every invite, every webhook, every message of every channel, and every channel attachment are deleted. Any discovery application is deleted. The guild record is then deleted, the guild is stopped on the main Gateway, and it is removed from the guild search index.

One Admin audit entry is recorded with the action delete_guild, the target type guild, and the guild ID in both the target and the metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

List guild members

GET/v1/admin/guilds/{guild_id}/members

Returns one page of guild member objects read from the main Gateway, without requiring membership. Requires guild:list:members.

Members come from the main Gateway

A guild the main Gateway cannot load answers 404 UNKNOWN_GUILD.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Query parameters

Field	Type	Description
limit?	integer	Maximum members to return (1-200, default 50)
offset?	integer	Members to skip before returning results (0-2147483647, default 0)

Response body

Field	Type	Description
members	array[guild member object]	Members in this page
total	integer	The total member count the main Gateway reported
limit1	integer	The limit the operation applied
offset1	integer	The offset the operation applied

¹ Both are echoed from the resolved query, so a request that omitted them reads back the defaults. A client advances the page by adding limit to offset

Response

Status	Body	Condition
200	response body	Member page was returned
500	error response	The API loses its connection to the main Gateway during the call

A member query the main Gateway reports as failed returns 502 BAD_GATEWAY, an unanswered call returns 504 GATEWAY_TIMEOUT, and an overloaded cluster returns 503 SERVICE_UNAVAILABLE.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Add guild member

PUT/v1/admin/guilds/{guild_id}/members/{user_id}Audit reason

Adds a user to a guild without an invite. Requires guild:force_add_member. The operation takes no request body.

Only the Admin ACL is evaluated.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The user to add

Response body

Field	Type	Description
success	boolean	Always true

Response

Status	Body	Condition
200	response body	Member was added, or the user was already a member
400	error response	MAX_GUILDS because the user is at their guild limit, or MAX_GUILD_MEMBERS because the guild is at its member limit
404	error response	UNKNOWN_USER because the user does not exist, or UNKNOWN_GUILD because the guild does not exist

Side effects

Fluxer creates the membership with the Admin force-add join source and restores a communication timeout still in force from a previous membership. The guild ban list is not consulted, so a banned user can be admitted. The suspicious activity phone gate does not run. The per-user guild limit and the guild member limit are still enforced.

Guild Member Add fires to the guild, the user’s sessions are joined to the guild on the main Gateway, and the member enters guild member search when the guild has an indexed member set. The ordinary join system message is created, and with it a Message Create Dispatch, unless the guild sets SUPPRESS_JOIN_NOTIFICATIONS or has no usable system channel. A bot target additionally records a BOT_ADD entry in the guild’s own audit log.

A user who is already a member keeps their existing membership. No membership is created, no counter moves, and no Dispatch is emitted. The Admin audit entry is still written.

One Admin audit entry is recorded with the action force_add_to_guild, the target type user, the added user as the target, and the guild ID in the metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Remove guild member

DELETE/v1/admin/guilds/{guild_id}/members/{user_id}Audit reason

Removes a member from a guild without banning them and returns 204 with an empty body. Requires guild:kick_member.

Removal also needs KICK_MEMBERS in the guild

The acting account must see the guild, hold KICK_MEMBERS in it, and rank above the target. A guild at MFA level 1 also requires an enrolled authenticator.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The member to remove

Response

Status	Body	Condition
204	empty	Member was removed
400	error response	TWO_FACTOR_REQUIRED in an MFA level 1 guild
4031	error response	MISSING_ACCESS when the acting account cannot see the guild, or MISSING_PERMISSIONS when KICK_MEMBERS is absent
404	error response	UNKNOWN_MEMBER, because the target is not a member, is the guild owner, or is the acting account

¹ MISSING_PERMISSIONS also covers a target who outranks the acting account

Side effects

Fluxer snapshots the membership metadata, including any communication timeout, so that a later rejoin restores it. It then deletes the membership, decreases the recorded member count by one, and detaches the user from the guild on the main Gateway. The member is removed from guild member search when the guild has an indexed member set.

Guild Member Remove fires to the guild. A MEMBER_KICK entry is written to the guild’s own audit log. The entry names the acting Admin account and has the audit reason, and the write fires Guild Audit Log Entry Create to sessions holding VIEW_AUDIT_LOG.

The removal creates no ban record, so the user can rejoin.

One Admin audit entry is recorded with the action kick_member, the target type guild_member, the removed user as the target, and the guild and user IDs in the metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Ban guild member

PUT/v1/admin/guilds/{guild_id}/bans/{user_id}Audit reason

Bans a user from a guild, optionally removes their recent messages, and returns 204 with an empty body. The target need not be a member. Requires guild:ban_member.

A ban also needs BAN_MEMBERS in the guild

The acting account must hold BAN_MEMBERS in the guild, and must rank above a target who is a member. A guild at MFA level 1 also requires an enrolled authenticator.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
user_id	snowflake	The user to ban

JSON body

Field	Type	Description
delete_message_seconds?1	integer	The window of recent messages to delete, in seconds (0-604800)
delete_message_days?1	integer	The window of recent messages to delete, in days (0-7, default 0)
reason?	?string	The guild ban reason stored on the ban record (at most 512 characters)
ban_duration_seconds?2	integer	The ban duration in seconds, either exactly 0 or between 60 and 63072000

¹ delete_message_seconds wins when both are supplied, and delete_message_days is otherwise multiplied by 86400. A resolved window of 0 deletes no message

² Omitting the field and sending 0 both produce a permanent ban. There is no field that sets an absolute expiry timestamp

Response

Status	Body	Condition
204	empty	User was banned
400	error response	Duration, reason, or message window validation fails, or TWO_FACTOR_REQUIRED in an MFA level 1 guild
403	error response	MISSING_PERMISSIONS because BAN_MEMBERS is absent in the guild or the target member outranks the acting account
404	error response	UNKNOWN_MEMBER because the target is the acting account, or UNKNOWN_USER because the user does not exist

The ban can also delete messages

The ban removes current membership and blocks later joins until its expiry or explicit removal. Messages inside the resolved deletion window are permanently deleted and are not restored when the ban ends.

Side effects

The ban record names the acting Admin account as moderator and has the expiry, the reason, the target’s last known IP address unless that address is on the ban exemption list, and the target’s lowercased email address. While the ban exists the guild also blocks that address and that email, as described by Guild moderation, and removing the ban releases both.

A positive deletion window queues a background job that deletes the target’s matching messages after the response, which fires Message Delete Bulk as deletion progresses.

Guild Ban Add fires to the guild. A target who was a member is then removed, which decreases the recorded member count, detaches the user from the guild on the main Gateway, removes the member from guild member search, and fires Guild Member Remove. The ban path snapshots no membership metadata, so a communication timeout in force at the moment of the ban is not restored on a later rejoin. This operation writes no entry to the guild’s own audit log, and it emits no Guild Audit Log Entry Create.

One Admin audit entry is recorded with the action ban_member, the target type guild_member, the banned user as the target, and the guild ID, user ID, delete_message_days value, and any supplied reason and duration in the metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

List guild emojis

GET/v1/admin/guilds/{guild_id}/emojis

Returns every custom emoji of a guild as Admin guild expression objects. Requires asset:purge.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response body

Field	Type	Description
guild_id	snowflake	The guild the listing covers, echoed from the path
emojis1	array[Admin guild expression object]	Every custom emoji of the guild

¹ The listing is not paginated and takes no query parameters

Response

Status	Body	Condition
200	response body	Emojis were returned, or the guild owns none

The operation does not verify that the guild exists, so an unknown guild ID returns an empty listing.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

List guild stickers

GET/v1/admin/guilds/{guild_id}/stickers

Returns every sticker of a guild as Admin guild expression objects. Requires asset:purge.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response body

Field	Type	Description
guild_id	snowflake	The guild the listing covers, echoed from the path
stickers1	array[Admin guild expression object]	Every sticker of the guild

¹ The listing is not paginated and takes no query parameters

Response

Status	Body	Condition
200	response body	Stickers were returned, or the guild owns none

The operation does not verify that the guild exists, so an unknown guild ID returns an empty listing.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Purge guild assets

DELETE/v1/admin/guilds/{guild_id}/assetsAudit reason

Deletes emoji and sticker records owned by a guild and queues their stored media for removal, reporting the outcome of every ID separately. Requires asset:purge.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

Field	Type	Description
ids1	array[string]	Emoji and sticker IDs to delete with their media, each 1 to 64 characters (at most 100)

¹ Each entry is trimmed, and Fluxer skips one that is then empty and any repeat of an entry already seen, so neither appears in processed or errors. An empty array is accepted and purges nothing

Response body

Field	Type	Description
processed	array[Admin guild asset purge result object]	Assets that were purged
errors	array[Admin guild asset purge error object]	Assets that could not be purged

Response

Status	Body	Condition
200	response body	The purge attempt completed, whether or not every ID succeeded

The operation does not verify that the guild exists. Under an unknown guild ID, an ID that matches another guild’s record lands in errors and every other ID is reported as unknown.

Successful asset purges cannot be undone

Every ID in processed loses its record and its stored media permanently. The operation still returns 200 when other IDs fail.

Side effects

A record owned by the guild in the path is deleted, and its stored media is queued for removal. The guild then receives one Guild Emojis Update or Guild Stickers Update Dispatch with its complete remaining expression set. A request that purges several records emits one such Dispatch per record.

A record owned by a different guild is left untouched and reported in errors. An ID with no record queues emoji and sticker media removal for that ID and is reported with the unknown asset type, so the operation also clears orphaned media.

Every entry in processed records its own Admin audit entry, with the numeric ID as the target. A purged emoji records purge_guild_emoji_asset with the target type guild_emoji, a purged sticker records purge_guild_sticker_asset with guild_sticker, and an unknown ID records purge_asset with asset. Entries in errors record nothing.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

List guild audit logs

GET/v1/admin/guilds/{guild_id}/audit-logs

Returns one page of the guild’s own in-app audit log, without requiring guild membership or VIEW_AUDIT_LOG. Requires guild:audit_log:view.

The page has the same shape and the same semantics as the public List guild audit logs operation, including the message deletion consolidation that operation performs.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Query parameters

Field	Type	Description
limit?	integer	Maximum entries to return (1-100, default 50)
before?1	snowflake	Return entries older than this entry ID
after?1	snowflake	Return entries newer than this entry ID
user_id?2	snowflake	Return only entries recorded for this actor
action_type?2	integer	Return only entries with this audit action value

¹ The two cursors are mutually exclusive. Supplying both fails with 400 INVALID_FORM_BODY and the validation code CANNOT_SPECIFY_BOTH_BEFORE_AND_AFTER against before

² Supplying either filter disables the consolidation of consecutive message deletion entries

Response body

Field	Type	Description
audit_log_entries	array[guild audit log entry object]	The returned page of audit entries
users	array[partial user object]	Users referenced by the returned entries
webhooks	array[audit log webhook object]	Webhooks referenced by the returned entries

Response

Status	Body	Condition
200	response body	Audit page was returned, or the guild has no matching entry
400	error response	before and after were supplied together

The operation does not verify that the guild exists, so an unknown guild ID returns an empty page.

Side effects

The read records no Admin audit entry and appends no ordinary entry to the guild’s own audit log. It still changes that log. Runs of consecutive message deletion entries are replaced with one bulk entry, and that replacement emits Guild Audit Log Entry Create, exactly as the public operation does.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Reload guild

POST/v1/admin/guilds/{guild_id}/reloadsAudit reason

Reloads a guild’s state on the main Gateway. Requires guild:reload. The operation takes no request body.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response body

Field	Type	Description
success	boolean	Always true

Response

Status	Body	Condition
200	response body	Reload command completed
404	error response	UNKNOWN_GUILD, because the guild does not exist
500	error response	The API loses its connection to the main Gateway during the call

A reload the main Gateway reports as failed returns 502 BAD_GATEWAY, an unanswered call returns 504 GATEWAY_TIMEOUT, and an overloaded cluster returns 503 SERVICE_UNAVAILABLE.

Side effects

The main Gateway reloads the guild’s current state from storage and fires one Guild Update Dispatch to every session subscribed to the guild. The operation changes no guild data.

One Admin audit entry is recorded with the action reload_guild, the target type guild, and the guild ID in both the target and the metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Shut down guild

POST/v1/admin/guilds/{guild_id}/shutdownsAudit reason

Unloads a guild from the main Gateway without deleting stored data. Requires guild:shutdown. The operation takes no request body.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response body

Field	Type	Description
success	boolean	Always true

Response

Status	Body	Condition
200	response body	Shutdown command completed
404	error response	UNKNOWN_GUILD, because the guild does not exist
500	error response	The API loses its connection to the main Gateway during the call

A shutdown the main Gateway reports as failed returns 502 BAD_GATEWAY, an unanswered call returns 504 GATEWAY_TIMEOUT, and an overloaded cluster returns 503 SERVICE_UNAVAILABLE.

Side effects

The main Gateway stops the guild process. Every session subscribed to the guild receives a Guild Delete Dispatch with unavailable true and reconnects after one second, which starts the guild again from stored data. Stored guild data is untouched, and Reload guild also starts a stopped guild.

One Admin audit entry is recorded with the action shutdown_guild, the target type guild, and the guild ID in both the target and the metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:guild:modify bucket.

Create guild archive

POST/v1/admin/guilds/{guild_id}/archives

Queues an asynchronous archive of the guild’s channels, messages, members, roles, and settings, and returns the created archive object. Requires archive:trigger:guild.

Archive status and downloads are read through Archives.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

Field	Type	Description
include_attachments?	boolean	Whether uploaded files are included in the archive (default false)

Response

Status	Body	Condition
200	archive object	Archive was created and queued
404	error response	UNKNOWN_GUILD, because the guild does not exist
500	error response	Archive creation or queueing fails

Side effects

The archive record is created with the acting Admin account as requested_by, a progress_percent of 0, a progress_step of Queued, and an expires_at that is never extended. The archive is built after the response is returned. A client reads progress through Get archive.

The operation emits no Gateway Dispatch and records no Admin audit entry.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.