Skip to content
Fluxer API

Admin API overview

The Admin API lets you manage accounts, guilds, messages and configuration on your instance. Every route is under /v1/admin and uses the same JSON format and error response as the HTTP API. It has its own credentials, ACLs and rate limits.

Send one of these credentials in the Authorization header. Authentication has the token formats.

CredentialHeader value
User session tokenThe token with no prefix
Admin OAuth2 access tokenBearer and the token, issued by the built-in Admin OAuth2 application
Admin API keyAdmin and the token

The account needs admin:authenticate or *. The API refuses bot tokens and access tokens from any other OAuth2 application. No Admin route needs an OAuth2 scope, MFA or sudo mode.

An Admin API key acts as the account that created it and only works on paths under /v1/admin. A request made with a key needs one of the route's ACLs on the key and one on the account that owns it, unless that account has *. Removing an ACL from the key or its owner takes effect on the next request.

Each route needs one or more ACLs, and the caller needs at least one of them. The wildcard * satisfies every ACL, including ones added later. Some routes need extra ACLs depending on the request, such as user:view:email on List users when you filter by email, and you need every one of those.

Update guild and Queue bulk job need a different ACL depending on what the request body changes.

Set user ACLs, Create Admin API key and Update Admin API key only accept values from the ACL registry. You can only grant ACLs you have yourself, and trying to grant any other ACL returns 403 MISSING_ACL. An account with * can grant any ACL.

List ACLs returns these values in this order. Expect values that aren't in this table.

ValueDescription
*Satisfies every Admin permission, including permissions introduced later
acl:set:userReplaces the Admin ACL set held by an account
admin_api_key:manageCreates, reads, renames and revokes Admin API keys
application:lookupReads Admin application resources and lists the applications whose bots are in a guild
application:list:by_ownerLists the applications one account owns
application:transfer_ownershipTransfers OAuth2 application ownership
archive:trigger:guildCreates and reads guild archives
archive:trigger:userCreates and reads user archives
archive:view_allReads and downloads archives
asset:purgeReads a guild's emojis and stickers, and purges guild media assets
audit_log:viewReads the Admin audit log
admin:authenticateLets the account use the Admin API, and is enough for List ACLs and Get current Admin user
jobs:viewReads background job state
jobs:cancelRequests background job cancellation
badge:createCreates custom badges
badge:deleteDeletes custom badges
badge:listReads custom badges
badge:updateUpdates custom badges
ban:email:addAdds and updates email blocklist entries
ban:email:checkReads the email blocklist
ban:email:removeRemoves email blocklist entries
ban:phrase:addAdds and updates phrase blocklist entries
ban:phrase:checkReads the phrase blocklist
ban:phrase:removeRemoves phrase blocklist entries
ban:ip:addAdds and updates ip blocklist entries
ban:ip:checkReads the ip blocklist
ban:ip:removeRemoves ip blocklist entries
ban:url:addAdds and updates url blocklist entries
ban:url:checkReads the url blocklist
ban:url:removeRemoves url blocklist entries
ban:url_domain:addAdds and updates url-domain blocklist entries
ban:url_domain:checkReads the url-domain blocklist
ban:url_domain:removeRemoves url-domain blocklist entries
ban:file_sha:addAdds and updates file-sha blocklist entries
ban:file_sha:checkReads the file-sha blocklist
ban:file_sha:removeRemoves file-sha blocklist entries
ban:avatar_hash:addAdds and updates avatar-hash blocklist entries
ban:avatar_hash:checkReads the avatar-hash blocklist
ban:avatar_hash:removeRemoves avatar-hash blocklist entries
ban:profile_substring:addAdds and updates profile-substring blocklist entries
ban:profile_substring:checkReads the profile-substring blocklist
ban:profile_substring:removeRemoves profile-substring blocklist entries
bulk:add:guild_membersQueues the bulk guild member addition task
bulk:delete:usersQueues the bulk account deletion task
bulk:delete:user_messagesQueues the bulk message deletion task
bulk:update:guild_featuresQueues the bulk guild feature task
bulk:update:user_flagsQueues the bulk account flag task
discovery:removeRemoves a guild from discovery
discovery:reviewReads, reviews and edits discovery applications, categories and listings
enforcement:annotateAdds notes to enforcement decisions
enforcement:viewReads enforcement decisions. Ending one needs this ACL plus the ACL for its kind
gateway:memory_statsReads main Gateway statistics, memory statistics and voice state counts
gateway:reload_allReloads guilds across the main Gateway
gift_codes:generateGenerates gift codes
guild:audit_log:viewReads a guild's ordinary audit log
guild:ban_memberBans a guild member and removes a guild ban
guild:deleteDeletes a guild
guild:force_add_memberAdds an account to a guild
guild:kick_memberRemoves a guild member
guild:list:membersReads guild member resources
guild:lookupReads and searches Admin guild resources, lists the threads of a guild, and queues and reads search index rebuilds
guild:reloadReloads one guild on the main Gateway
guild:shutdownStops one guild on the main Gateway
guild:transfer_ownershipTransfers guild ownership
guild:update:badgesReplaces the custom badges of a guild
guild:update:featuresAdds and removes guild features
guild:update:nameUpdates a guild name
guild:update:settingsUpdates general guild settings and clears guild fields
guild:update:vanityUpdates a guild custom invite code
instance:config:updateUpdates instance configuration and branding, tests SMTP, manages registration URLs and migrates SSO subjects
instance:config:viewReads instance configuration
instance:limit_config:updateReplaces the instance-wide limit configuration
instance:limit_config:viewReads the instance-wide limit configuration
message:delete_allQueues deletion of every message one account sent, and deletes a thread
message:deleteDeletes one message
message:lookupReads, browses and searches messages through the Admin API
message:shredQueues an explicit message shred job and reads its state
registration:reviewReads and decides pending registrations
report:deleteDeletes a report with its stored evidence
report:resolveUpdates and resolves reports, adds notes to them and places legal holds on them
report:viewReads and searches reports and their notes
report:view:reporter_piiUnredacts the contact fields a reporter supplied
system_dm:sendSends an official direct message from the instance to one or many accounts
user:cancel:bulk_message_deletionCancels the bulk message deletion an account scheduled for itself
user:create:password_reset_linkCreates a password reset link on an instance where members sign in with a username
user:delete:recovery_kitRevokes a recovery kit on an instance where members sign in with a username
user:deleteSchedules or cancels account deletion
user:list:dm_channelsReads a user's direct message and group direct message channels
user:list:guildsReads a user's guild memberships
user:list:relationshipsReads a user's relationships
user:list:sessionsReads a user's login sessions and lists app sessions by platform
user:lookupReads and searches the base Admin user resource
user:remove:relationshipRemoves one relationship or every relationship in one category
user:view:contact_logReads a user's identity and contact change log
user:view:dobUnredacts user dates of birth
user:view:emailUnredacts user email addresses and email verification state
user:view:ipUnredacts the last active IP address and the location derived from it
user:temp_banSuspends accounts and lifts suspensions
user:update:badgesReplaces the custom badges of an account
user:update:bot_statusUpdates bot and system account state
user:update:dobUpdates dates of birth
user:update:emailUpdates the email address, verifies it, resends verification, sends a password reset and binds SSO subjects
user:update:flagsUpdates account flags and premium flags, and ends every login session of an account
user:update:mfaReads and removes a user's WebAuthn credentials, and removes MFA state
user:update:profileClears profile fields
user:update:traitsReplaces account traits
user:update:usernameUpdates usernames and discriminators
voice:join_token:createCreates join tokens for new voice servers
voice:join_token:listReads join tokens
voice:join_token:revokeRevokes join tokens
voice:region:createCreates voice regions
voice:region:deleteDeletes voice regions
voice:region:listReads voice regions
voice:region:updateUpdates voice regions
voice:server:createRegisters a voice server in a region
voice:server:deleteDeletes a registered voice server
voice:server:listReads registered voice servers
voice:server:updateUpdates a registered voice server

An ACL that unredacts a field doesn't give access to any route by itself. It only adds that field to responses you can already get.

An Admin audit entry records one Admin action against one target. Almost every Admin route records an entry, reads included. A request refused by authentication, ACLs, rate limits or validation records nothing.

Read entries store IDs, filters and counts, never query text, email addresses, IP addresses or other free-form input.

FieldTypeDescription
log_idsnowflakeThe ID of the audit entry
admin_user_idsnowflakeThe ID of the acting account, or 0 for an action run with rexctl
admin_user?Admin user summary objectThe acting account, or null when it no longer exists
target_typestringThe audit target type (1-256 characters)
target_idstringThe target ID as a decimal string, or 0 when the target has no snowflake
target_user?Admin user summary objectThe target account, or null when the target is not an account
target_guild?Admin guild summary objectThe target guild, or null when the target is not a guild
target_channel?Admin channel summary objectThe target channel or the channel in channel_id metadata, or null
related_usersmap[snowflake, Admin user summary object]The accounts the entry references, keyed by ID
related_guildsmap[snowflake, Admin guild summary object]The guilds the entry references, keyed by ID
related_channelsmap[snowflake, Admin channel summary object]The channels the entry references, keyed by ID
actionstringThe audit action (1-256 characters)
accessstringread or write
audit_log_reason?stringThe audit reason, or null
metadatamap[string, string]The extra values the route recorded
created_atISO8601 timestampWhen the entry was recorded

When an Admin API key made the request, metadata.via is api_key: followed by the key ID. When rexctl made it, metadata.via is rexctl, and metadata.host_user is set when rexctl knows who ran it.

{
"log_id": "1501314428688998182",
"admin_user_id": "1489200013322551296",
"admin_user": {
"id": "1489200013322551296",
"username": "operator",
"discriminator": "0042",
"global_name": "Operator"
},
"target_type": "user",
"target_id": "1493004551122763776",
"target_user": {
"id": "1493004551122763776",
"username": "subject",
"discriminator": "0007",
"global_name": null
},
"target_guild": null,
"target_channel": null,
"related_users": {},
"related_guilds": {},
"related_channels": {},
"action": "change_username",
"access": "write",
"audit_log_reason": "Impersonation report 4821",
"metadata": {
"old_username": "subj3ct",
"new_username": "subject",
"discriminator": "7"
},
"created_at": "2026-05-14T09:12:44.183000+00:00"
}
FieldTypeDescription
idsnowflakeThe ID of the account
usernamestringThe username of the account
discriminatorstringThe discriminator, zero-padded to four digits
global_name?stringThe display name of the account
FieldTypeDescription
idsnowflakeThe ID of the guild
namestringThe name of the guild
FieldTypeDescription
idsnowflakeThe ID of the channel
name?stringThe name of the channel, or null for a direct message channel
typeintegerThe channel type
guild_id?snowflakeThe ID of the guild, or null for a direct message channel

Expect values that aren't in this table.

ValueDescription
userUser account
guildGuild
guild_memberGuild membership
guild_emojiGuild emoji asset
guild_stickerGuild sticker asset
messageMessage
message_deletionDeletion of every message one account sent
message_shredMessage shred job for one account
channelChannel
assetStored media asset
applicationOAuth2 application
reportUser report
search_indexSearch index
system_dmSystem DM broadcast
gift_codeBatch of generated gift codes
bulk_jobBackground job
admin_api_keyAdmin API key
audit_logAdmin audit entry
enforcement_decisionEnforcement decision
archiveArchive list
admin_aclAdmin ACL registry
blocklistBlocklist catalog
discovery_categoryDiscovery category
instance_configInstance configuration
limit_configLimit configuration
registration_urlAdmin-issued registration URL
gatewayGateway cluster
systemAPI process that served the request
voice_regionVoice region
voice_serverVoice server registration
ipIP blocklist entry
emailExact email blocklist entry
phrasePhrase blocklist entry
urlExact URL blocklist entry
url_domainURL domain blocklist entry
file_shaFile SHA-256 blocklist entry
avatar_hashAvatar hash blocklist entry
profile_substringProfile substring blocklist entry

Expect values that aren't in these tables.

These entries have access set to read.

ValueDescription
check_blocklist_entryA value was checked against a blocklist
get_admin_api_keyAn Admin API key was read
get_applicationAn application was read
get_archiveAn archive was read
get_archive_download_urlA download URL for an archive was issued
get_audit_logAn Admin audit entry was read
get_gateway_statsGateway node statistics were read
get_guildA guild was read
get_instance_configThe instance configuration was read
get_limit_configThe limit configuration was read
get_messageA message and its surrounding messages were read
get_message_shred_statusThe state of a message shred job was read
get_reportA report was read
get_userAn account was read
get_voice_regionA voice region was read
get_voice_serverA voice server was read
get_voice_state_countsGateway voice state counts were read
list_admin_aclsThe Admin ACL registry was read
list_admin_api_keysThe acting Admin's API keys were listed
list_app_sessionsActive app sessions were listed for one platform and release channel
list_archivesArchives were listed
list_audit_logsA page of the Admin audit log was read
list_badgesThe custom badges were listed
list_blocklist_entriesA page of blocklist entries was read
list_blocklistsThe blocklist catalog was read
list_channel_messagesThe messages of a channel were listed
list_discovery_applicationsPending discovery applications were read
list_discovery_categoriesThe discovery categories were read
list_discovery_category_listingsA page of the discovery listings in one category was read
list_discovery_listingsApproved discovery listings were read
list_enforcement_decisionsThe enforcement decisions about an account or community, or the review queue, were listed
list_guild_applicationsThe applications whose bots are members of a guild were read
list_guild_audit_logsThe audit log of a guild was read
list_guild_emojisThe custom emojis of a guild were listed
list_guild_membersThe members of a guild were listed
list_guild_memory_statsGuild memory statistics were listed
list_guild_stickersThe stickers of a guild were listed
list_guild_threadsThe threads of a guild were listed
list_network_block_candidatesThe networks an account used in the last 30 days were listed, with how many other accounts share each
list_pending_registrationsPending registrations were read
list_report_notesThe internal notes on a report were listed
list_report_reasonsThe report reason catalog was listed
list_user_applicationsThe applications an account owns were read
list_user_change_logThe contact change log of an account was read
list_user_dm_channelsThe direct message channels of an account were read
list_user_guildsThe guild memberships of an account were read
list_user_relationshipsThe relationships of an account were read
list_user_sessionsAn account's login sessions were read
list_user_sso_identitiesThe single sign-on identities of an account were read
list_voice_join_tokensVoice join tokens were listed
list_voice_regionsVoice regions were listed
list_voice_serversThe voice servers of a region were listed
list_webauthn_credentialsAn account's WebAuthn credentials were read
lookup_sso_identityThe account holding a single sign-on subject was looked up
search_audit_logsThe Admin audit log was searched
search_guildsGuilds were listed or searched
search_messagesThe messages of a channel were searched, or one message was looked up
search_reportsReports were listed or searched
search_usersAccounts were listed or searched
view_enforcement_decisionAn enforcement decision was read

These entries have access set to write.

ValueDescription
annotate_enforcement_decisionA note was added to an enforcement decision
annotate_reportA note was added to a report
approve_discovery_applicationA discovery application was approved
approve_registrationA pending registration was approved
auto_resolve_reports_on_deletionThe pending reports against an account were processed as part of its deletion
ban_avatar_hashAn avatar hash was added to the avatar blocklist
ban_emailAn address was added to the email blocklist
ban_file_shaA file hash was added to the attachment blocklist
ban_ipAn address was added to the IP blocklist
ban_ip_skipped_exemptAn IP blocklist entry was skipped because the address is exempt
ban_memberAn account was banned from a guild
ban_phraseA phrase was added to the message phrase blocklist
ban_profile_substringA substring was added to the profile substring blocklist
ban_urlA URL was added to the URL blocklist
ban_url_domainA domain was added to the URL domain blocklist
bulk_add_guild_membersA bulk guild member addition was queued or applied
bulk_ban_file_shasA queued bulk file hash blocklist job was applied
bulk_delete_user_messagesA queued bulk message deletion job was applied
bulk_schedule_deletionA bulk account deletion schedule was queued or applied
bulk_update_guild_featuresA bulk guild feature change was queued or applied
bulk_update_user_flagsA bulk account flag change was queued or applied
cancel_bulk_message_deletionA bulk message deletion an account scheduled for itself was canceled
cancel_deletionA scheduled account deletion was canceled
cancel_jobCancellation of a job was requested
change_dobA date of birth was changed
change_emailAn email address was changed
change_usernameA username or discriminator was changed
clear_fieldsProfile fields of an account, or fields of a guild, were cleared
clear_report_legal_holdThe legal hold on a report was cleared
clear_role_iconThe icon of a guild role was cleared
create_admin_api_keyAn Admin API key was created
create_badgeA custom badge was made
create_password_reset_linkA password reset link was created for an account
create_registration_urlA registration URL was issued
create_sign_in_linkA sign-in link was created for an admin account
create_userAn account was created by an Admin
create_voice_join_tokenA voice join token was created
create_voice_regionA voice region was created
create_voice_serverA voice server was registered
create_voice_server_test_tokenA test token for a voice server was signed
delete_all_user_messagesDeletion of every message an account sent was queued
delete_all_user_messages_dry_runDeletion of every message an account sent was previewed with dry_run, and nothing was deleted
delete_badgeA custom badge was deleted
delete_guildA guild was deleted
delete_messageOne message was deleted
delete_reportA report was deleted with its stored evidence
delete_threadA thread was deleted
delete_voice_regionA voice region was deleted
delete_voice_serverA registered voice server was deleted
delete_webauthn_credentialA WebAuthn credential was removed from an account
disable_mfaMulti-factor authentication was disabled on an account
end_enforcement_decisionAn enforcement decision was ended as lifted or reversed
force_add_to_guildAn account was added to a guild while bypassing the ban check
generate_gift_codesGift codes were generated
hide_built_in_badgeA built-in community badge was hidden on this instance
kick_memberA member was removed from a guild
limit_featuresA feature limit decision was recorded for an account
link_sso_identityA single sign-on subject was bound to an account by hand
migrate_sso_identitiesSingle sign-on subjects were moved from an earlier provider ID to the provider in use
move_badgeOne custom badge was moved in the display order
preview_message_shredThe messages a shred would delete were listed
purge_assetA stored media asset was purged
purge_guild_emoji_assetA guild emoji asset was purged
purge_guild_sticker_assetA guild sticker asset was purged
queue_bulk_jobA bulk job was queued
queue_message_shredA message shred job was queued
queue_refresh_indexA search index rebuild was requested
reject_discovery_applicationA discovery application was rejected
reject_registrationA pending registration was rejected
reload_guildOne guild was reloaded on the main Gateway
reload_guildsMany guilds were reloaded on the main Gateway
remove_discovery_listingA guild was removed from discovery
remove_relationshipOne relationship was removed from an account
remove_registration_urlA revoked registration URL was removed from the list
remove_relationships_by_categoryEvery relationship in one category was removed from an account
rename_registration_urlA registration URL was given a new label
reorder_badgesThe display order of the custom badges was changed
replace_built_in_badge_imageThe image of a built-in badge was replaced
resend_verification_emailAn email verification message was requested again for an account
reset_built_in_badge_imageA built-in badge went back to its built-in image
resolve_reportA report was updated or resolved
revoke_admin_api_keyAn Admin API key was revoked
revoke_recovery_kitThe recovery kit of an account was revoked
revoke_registration_urlA registration URL was revoked
revoke_voice_join_tokenA voice join token was revoked
schedule_deletionAccount deletion was scheduled
send_password_resetA password reset message was requested for an account
set_aclsThe Admin ACL set of an account was replaced
set_bot_statusThe bot flag of an account was changed
set_report_legal_holdA legal hold was placed on a report
set_system_statusThe system flag of an account was changed
set_traitsAccount traits were replaced
shutdown_guildOne guild was stopped on the main Gateway
show_built_in_badgeA hidden built-in community badge was shown again
system_dm.sendA system DM broadcast was created
temp_banAn account was suspended for a time or permanently
terminate_sessionsEvery login session of an account was revoked
test_smtp_connectionAn SMTP connection test was run
transfer_ownershipOwnership of a guild or an OAuth2 application was transferred
trigger_guild_archiveA guild archive was created
trigger_user_archiveA user archive was created
unbanA suspension without an enforcement decision was lifted
unban_avatar_hashAn avatar hash was removed from the avatar blocklist
unban_emailAn address was removed from the email blocklist
unban_file_shaA file hash was removed from the attachment blocklist
unban_ipAn address was removed from the IP blocklist
unban_memberA guild ban was removed
unban_phraseA phrase was removed from the message phrase blocklist
unban_profile_substringA substring was removed from the profile substring blocklist
unban_urlA URL was removed from the URL blocklist
unban_url_domainA domain was removed from the URL domain blocklist
unlink_sso_identitiesThe single sign-on subjects of an account were released
update_admin_api_keyAn Admin API key was renamed or its ACLs were replaced
update_badgeA custom badge was updated
update_badge_settingsThe limits on how many custom badges an account or guild can have were changed
update_discovery_categoriesGuilds were moved to a discovery category
update_discovery_listingA discovery listing was edited
update_featuresGuild features were added or removed
update_flagsAccount flags were changed
update_guildA guild update changed none of the fields that have their own action
update_guild_badgesThe custom badges of a guild were replaced
update_instance_configThe instance configuration was updated
update_limit_configThe limit configuration was replaced
update_nameA guild name was changed
update_premium_flagsPremium flags were changed
update_settingsGeneral guild settings were changed
update_user_badgesThe custom badges of an account were replaced
update_vanityA guild custom invite code was changed
update_voice_regionA voice region was updated
update_voice_serverA registered voice server was updated
upload_branding_assetAn instance branding asset was uploaded or cleared
use_sign_in_linkAn admin signed in with a sign-in link
verify_emailAn email address was marked verified
warn_userA warning decision was recorded for an account

Send X-Audit-Log-Reason on any route marked Audit reason, and the API stores it in audit_log_reason on each entry the request records. The API trims the value and strips control characters. A blank value or one longer than 512 characters is dropped without failing the request. Routes that require a reason, such as the enforcement routes, return 400 when the value is missing or dropped. Send the value as plain UTF-8, because the API doesn't percent-decode it.

An Admin error uses the same format as the HTTP API error response.

These errors can come from any Admin route.

StatusBodyCondition
400error responseINVALID_FORM_BODY when the path, query or body is invalid
401error responseUNAUTHORIZED when the credential is missing, invalid or a bot token
403error responseACCESS_DENIED for an access token from an OAuth2 application other than Admin
403error responseMISSING_PERMISSIONS when the account holds neither admin:authenticate nor *
403error responseMISSING_ACL when the caller holds none of the route's ACLs
429error responseRATE_LIMITED when a rate limit is hit

Admin rate limits count each account and credential type separately, and an Admin API key never shares its owner's session limits. See Rate limits for the headers and the global limit.

GET/v1/admin/aclsAudit reason

Returns every value in the ACL registry. You need admin:authenticate.

FieldTypeDescription
aclsarray[string]The ACL registry, the same for every caller
StatusBodyCondition
200response bodyThe registry was returned

Records a list_admin_acls audit entry.

The rate limit is 200 requests per minute, on the admin:lookup bucket.

GET/v1/admin/audit-logsAudit reason

Returns a page of Admin audit entries, newest first by default. You need audit_log:view.

FieldTypeDescription
q?stringSearch action, target_type, target_id and audit_log_reason (1-1,024 characters)
admin_user_id?snowflakeOnly entries by this acting account
target_type?stringOnly entries with this target type (1-64 characters)
target_id?stringOnly entries with this target ID
access?stringread or write
sort_by?stringcreatedAt or relevance, used only with q (default createdAt)
sort_order?stringasc or desc, used only with q (default desc)
limit?integerThe maximum number of entries to return (1-200, default 50)
offset?integerThe number of entries to skip (default 0)

Without a search index, the API ignores q and only filters the newest limit plus offset entries, so a page and total can come back short.

FieldTypeDescription
logsarray[Admin audit entry object]The entries in this page
totalintegerThe number of entries that match
StatusBodyCondition
200response bodyThe page was returned

Records a search_audit_logs audit entry when q is set and list_audit_logs otherwise, without the query text.

The rate limit is 100 requests per minute, on the admin:audit_log bucket.

GET/v1/admin/audit-logs/{log_id}Audit reason

Returns one Admin audit entry. You need audit_log:view.

StatusBodyCondition
200Admin audit entry objectThe entry was returned
404error responseNOT_FOUND when no entry has that ID

Records a get_audit_log audit entry.

The rate limit is 100 requests per minute, on the admin:audit_log bucket.