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.
Authentication
Section titled “Authentication”Send one of these credentials in the Authorization header. Authentication has the token formats.
| Credential | Header value |
|---|---|
| User session token | The token with no prefix |
| Admin OAuth2 access token | Bearer and the token, issued by the built-in Admin OAuth2 application |
| Admin API key | Admin 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.
ACL evaluation
Section titled “ACL evaluation”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.
ACL registry
Section titled “ACL registry”List ACLs returns these values in this order. Expect values that aren't in this table.
| Value | Description |
|---|---|
| * | Satisfies every Admin permission, including permissions introduced later |
| acl:set:user | Replaces the Admin ACL set held by an account |
| admin_api_key:manage | Creates, reads, renames and revokes Admin API keys |
| application:lookup | Reads Admin application resources and lists the applications whose bots are in a guild |
| application:list:by_owner | Lists the applications one account owns |
| application:transfer_ownership | Transfers OAuth2 application ownership |
| archive:trigger:guild | Creates and reads guild archives |
| archive:trigger:user | Creates and reads user archives |
| archive:view_all | Reads and downloads archives |
| asset:purge | Reads a guild's emojis and stickers, and purges guild media assets |
| audit_log:view | Reads the Admin audit log |
| admin:authenticate | Lets the account use the Admin API, and is enough for List ACLs and Get current Admin user |
| jobs:view | Reads background job state |
| jobs:cancel | Requests background job cancellation |
| badge:create | Creates custom badges |
| badge:delete | Deletes custom badges |
| badge:list | Reads custom badges |
| badge:update | Updates custom badges |
| ban:email:add | Adds and updates email blocklist entries |
| ban:email:check | Reads the email blocklist |
| ban:email:remove | Removes email blocklist entries |
| ban:phrase:add | Adds and updates phrase blocklist entries |
| ban:phrase:check | Reads the phrase blocklist |
| ban:phrase:remove | Removes phrase blocklist entries |
| ban:ip:add | Adds and updates ip blocklist entries |
| ban:ip:check | Reads the ip blocklist |
| ban:ip:remove | Removes ip blocklist entries |
| ban:url:add | Adds and updates url blocklist entries |
| ban:url:check | Reads the url blocklist |
| ban:url:remove | Removes url blocklist entries |
| ban:url_domain:add | Adds and updates url-domain blocklist entries |
| ban:url_domain:check | Reads the url-domain blocklist |
| ban:url_domain:remove | Removes url-domain blocklist entries |
| ban:file_sha:add | Adds and updates file-sha blocklist entries |
| ban:file_sha:check | Reads the file-sha blocklist |
| ban:file_sha:remove | Removes file-sha blocklist entries |
| ban:avatar_hash:add | Adds and updates avatar-hash blocklist entries |
| ban:avatar_hash:check | Reads the avatar-hash blocklist |
| ban:avatar_hash:remove | Removes avatar-hash blocklist entries |
| ban:profile_substring:add | Adds and updates profile-substring blocklist entries |
| ban:profile_substring:check | Reads the profile-substring blocklist |
| ban:profile_substring:remove | Removes profile-substring blocklist entries |
| bulk:add:guild_members | Queues the bulk guild member addition task |
| bulk:delete:users | Queues the bulk account deletion task |
| bulk:delete:user_messages | Queues the bulk message deletion task |
| bulk:update:guild_features | Queues the bulk guild feature task |
| bulk:update:user_flags | Queues the bulk account flag task |
| discovery:remove | Removes a guild from discovery |
| discovery:review | Reads, reviews and edits discovery applications, categories and listings |
| enforcement:annotate | Adds notes to enforcement decisions |
| enforcement:view | Reads enforcement decisions. Ending one needs this ACL plus the ACL for its kind |
| gateway:memory_stats | Reads main Gateway statistics, memory statistics and voice state counts |
| gateway:reload_all | Reloads guilds across the main Gateway |
| gift_codes:generate | Generates gift codes |
| guild:audit_log:view | Reads a guild's ordinary audit log |
| guild:ban_member | Bans a guild member and removes a guild ban |
| guild:delete | Deletes a guild |
| guild:force_add_member | Adds an account to a guild |
| guild:kick_member | Removes a guild member |
| guild:list:members | Reads guild member resources |
| guild:lookup | Reads and searches Admin guild resources, lists the threads of a guild, and queues and reads search index rebuilds |
| guild:reload | Reloads one guild on the main Gateway |
| guild:shutdown | Stops one guild on the main Gateway |
| guild:transfer_ownership | Transfers guild ownership |
| guild:update:badges | Replaces the custom badges of a guild |
| guild:update:features | Adds and removes guild features |
| guild:update:name | Updates a guild name |
| guild:update:settings | Updates general guild settings and clears guild fields |
| guild:update:vanity | Updates a guild custom invite code |
| instance:config:update | Updates instance configuration and branding, tests SMTP, manages registration URLs and migrates SSO subjects |
| instance:config:view | Reads instance configuration |
| instance:limit_config:update | Replaces the instance-wide limit configuration |
| instance:limit_config:view | Reads the instance-wide limit configuration |
| message:delete_all | Queues deletion of every message one account sent, and deletes a thread |
| message:delete | Deletes one message |
| message:lookup | Reads, browses and searches messages through the Admin API |
| message:shred | Queues an explicit message shred job and reads its state |
| registration:review | Reads and decides pending registrations |
| report:delete | Deletes a report with its stored evidence |
| report:resolve | Updates and resolves reports, adds notes to them and places legal holds on them |
| report:view | Reads and searches reports and their notes |
| report:view:reporter_pii | Unredacts the contact fields a reporter supplied |
| system_dm:send | Sends an official direct message from the instance to one or many accounts |
| user:cancel:bulk_message_deletion | Cancels the bulk message deletion an account scheduled for itself |
| user:create:password_reset_link | Creates a password reset link on an instance where members sign in with a username |
| user:delete:recovery_kit | Revokes a recovery kit on an instance where members sign in with a username |
| user:delete | Schedules or cancels account deletion |
| user:list:dm_channels | Reads a user's direct message and group direct message channels |
| user:list:guilds | Reads a user's guild memberships |
| user:list:relationships | Reads a user's relationships |
| user:list:sessions | Reads a user's login sessions and lists app sessions by platform |
| user:lookup | Reads and searches the base Admin user resource |
| user:remove:relationship | Removes one relationship or every relationship in one category |
| user:view:contact_log | Reads a user's identity and contact change log |
| user:view:dob | Unredacts user dates of birth |
| user:view:email | Unredacts user email addresses and email verification state |
| user:view:ip | Unredacts the last active IP address and the location derived from it |
| user:temp_ban | Suspends accounts and lifts suspensions |
| user:update:badges | Replaces the custom badges of an account |
| user:update:bot_status | Updates bot and system account state |
| user:update:dob | Updates dates of birth |
| user:update:email | Updates the email address, verifies it, resends verification, sends a password reset and binds SSO subjects |
| user:update:flags | Updates account flags and premium flags, and ends every login session of an account |
| user:update:mfa | Reads and removes a user's WebAuthn credentials, and removes MFA state |
| user:update:profile | Clears profile fields |
| user:update:traits | Replaces account traits |
| user:update:username | Updates usernames and discriminators |
| voice:join_token:create | Creates join tokens for new voice servers |
| voice:join_token:list | Reads join tokens |
| voice:join_token:revoke | Revokes join tokens |
| voice:region:create | Creates voice regions |
| voice:region:delete | Deletes voice regions |
| voice:region:list | Reads voice regions |
| voice:region:update | Updates voice regions |
| voice:server:create | Registers a voice server in a region |
| voice:server:delete | Deletes a registered voice server |
| voice:server:list | Reads registered voice servers |
| voice:server:update | Updates 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.
Admin audit entry object
Section titled “Admin audit entry object”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.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| log_id | snowflake | The ID of the audit entry |
| admin_user_id | snowflake | The ID of the acting account, or 0 for an action run with rexctl |
| admin_user | ?Admin user summary object | The acting account, or null when it no longer exists |
| target_type | string | The audit target type (1-256 characters) |
| target_id | string | The target ID as a decimal string, or 0 when the target has no snowflake |
| target_user | ?Admin user summary object | The target account, or null when the target is not an account |
| target_guild | ?Admin guild summary object | The target guild, or null when the target is not a guild |
| target_channel | ?Admin channel summary object | The target channel or the channel in channel_id metadata, or null |
| related_users | map[snowflake, Admin user summary object] | The accounts the entry references, keyed by ID |
| related_guilds | map[snowflake, Admin guild summary object] | The guilds the entry references, keyed by ID |
| related_channels | map[snowflake, Admin channel summary object] | The channels the entry references, keyed by ID |
| action | string | The audit action (1-256 characters) |
| access | string | read or write |
| audit_log_reason | ?string | The audit reason, or null |
| metadata | map[string, string] | The extra values the route recorded |
| created_at | ISO8601 timestamp | When 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.
Example
Section titled “Example”{ "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"}Admin user summary object
Section titled “Admin user summary object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the account |
| username | string | The username of the account |
| discriminator | string | The discriminator, zero-padded to four digits |
| global_name | ?string | The display name of the account |
Admin guild summary object
Section titled “Admin guild summary object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the guild |
| name | string | The name of the guild |
Admin channel summary object
Section titled “Admin channel summary object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the channel |
| name | ?string | The name of the channel, or null for a direct message channel |
| type | integer | The channel type |
| guild_id | ?snowflake | The ID of the guild, or null for a direct message channel |
Audit target types
Section titled “Audit target types”Expect values that aren't in this table.
| Value | Description |
|---|---|
| user | User account |
| guild | Guild |
| guild_member | Guild membership |
| guild_emoji | Guild emoji asset |
| guild_sticker | Guild sticker asset |
| message | Message |
| message_deletion | Deletion of every message one account sent |
| message_shred | Message shred job for one account |
| channel | Channel |
| asset | Stored media asset |
| application | OAuth2 application |
| report | User report |
| search_index | Search index |
| system_dm | System DM broadcast |
| gift_code | Batch of generated gift codes |
| bulk_job | Background job |
| admin_api_key | Admin API key |
| audit_log | Admin audit entry |
| enforcement_decision | Enforcement decision |
| archive | Archive list |
| admin_acl | Admin ACL registry |
| blocklist | Blocklist catalog |
| discovery_category | Discovery category |
| instance_config | Instance configuration |
| limit_config | Limit configuration |
| registration_url | Admin-issued registration URL |
| gateway | Gateway cluster |
| system | API process that served the request |
| voice_region | Voice region |
| voice_server | Voice server registration |
| ip | IP blocklist entry |
| Exact email blocklist entry | |
| phrase | Phrase blocklist entry |
| url | Exact URL blocklist entry |
| url_domain | URL domain blocklist entry |
| file_sha | File SHA-256 blocklist entry |
| avatar_hash | Avatar hash blocklist entry |
| profile_substring | Profile substring blocklist entry |
Audit actions
Section titled “Audit actions”Expect values that aren't in these tables.
Read actions
Section titled “Read actions”These entries have access set to read.
| Value | Description |
|---|---|
| check_blocklist_entry | A value was checked against a blocklist |
| get_admin_api_key | An Admin API key was read |
| get_application | An application was read |
| get_archive | An archive was read |
| get_archive_download_url | A download URL for an archive was issued |
| get_audit_log | An Admin audit entry was read |
| get_gateway_stats | Gateway node statistics were read |
| get_guild | A guild was read |
| get_instance_config | The instance configuration was read |
| get_limit_config | The limit configuration was read |
| get_message | A message and its surrounding messages were read |
| get_message_shred_status | The state of a message shred job was read |
| get_report | A report was read |
| get_user | An account was read |
| get_voice_region | A voice region was read |
| get_voice_server | A voice server was read |
| get_voice_state_counts | Gateway voice state counts were read |
| list_admin_acls | The Admin ACL registry was read |
| list_admin_api_keys | The acting Admin's API keys were listed |
| list_app_sessions | Active app sessions were listed for one platform and release channel |
| list_archives | Archives were listed |
| list_audit_logs | A page of the Admin audit log was read |
| list_badges | The custom badges were listed |
| list_blocklist_entries | A page of blocklist entries was read |
| list_blocklists | The blocklist catalog was read |
| list_channel_messages | The messages of a channel were listed |
| list_discovery_applications | Pending discovery applications were read |
| list_discovery_categories | The discovery categories were read |
| list_discovery_category_listings | A page of the discovery listings in one category was read |
| list_discovery_listings | Approved discovery listings were read |
| list_enforcement_decisions | The enforcement decisions about an account or community, or the review queue, were listed |
| list_guild_applications | The applications whose bots are members of a guild were read |
| list_guild_audit_logs | The audit log of a guild was read |
| list_guild_emojis | The custom emojis of a guild were listed |
| list_guild_members | The members of a guild were listed |
| list_guild_memory_stats | Guild memory statistics were listed |
| list_guild_stickers | The stickers of a guild were listed |
| list_guild_threads | The threads of a guild were listed |
| list_network_block_candidates | The networks an account used in the last 30 days were listed, with how many other accounts share each |
| list_pending_registrations | Pending registrations were read |
| list_report_notes | The internal notes on a report were listed |
| list_report_reasons | The report reason catalog was listed |
| list_user_applications | The applications an account owns were read |
| list_user_change_log | The contact change log of an account was read |
| list_user_dm_channels | The direct message channels of an account were read |
| list_user_guilds | The guild memberships of an account were read |
| list_user_relationships | The relationships of an account were read |
| list_user_sessions | An account's login sessions were read |
| list_user_sso_identities | The single sign-on identities of an account were read |
| list_voice_join_tokens | Voice join tokens were listed |
| list_voice_regions | Voice regions were listed |
| list_voice_servers | The voice servers of a region were listed |
| list_webauthn_credentials | An account's WebAuthn credentials were read |
| lookup_sso_identity | The account holding a single sign-on subject was looked up |
| search_audit_logs | The Admin audit log was searched |
| search_guilds | Guilds were listed or searched |
| search_messages | The messages of a channel were searched, or one message was looked up |
| search_reports | Reports were listed or searched |
| search_users | Accounts were listed or searched |
| view_enforcement_decision | An enforcement decision was read |
Write actions
Section titled “Write actions”These entries have access set to write.
| Value | Description |
|---|---|
| annotate_enforcement_decision | A note was added to an enforcement decision |
| annotate_report | A note was added to a report |
| approve_discovery_application | A discovery application was approved |
| approve_registration | A pending registration was approved |
| auto_resolve_reports_on_deletion | The pending reports against an account were processed as part of its deletion |
| ban_avatar_hash | An avatar hash was added to the avatar blocklist |
| ban_email | An address was added to the email blocklist |
| ban_file_sha | A file hash was added to the attachment blocklist |
| ban_ip | An address was added to the IP blocklist |
| ban_ip_skipped_exempt | An IP blocklist entry was skipped because the address is exempt |
| ban_member | An account was banned from a guild |
| ban_phrase | A phrase was added to the message phrase blocklist |
| ban_profile_substring | A substring was added to the profile substring blocklist |
| ban_url | A URL was added to the URL blocklist |
| ban_url_domain | A domain was added to the URL domain blocklist |
| bulk_add_guild_members | A bulk guild member addition was queued or applied |
| bulk_ban_file_shas | A queued bulk file hash blocklist job was applied |
| bulk_delete_user_messages | A queued bulk message deletion job was applied |
| bulk_schedule_deletion | A bulk account deletion schedule was queued or applied |
| bulk_update_guild_features | A bulk guild feature change was queued or applied |
| bulk_update_user_flags | A bulk account flag change was queued or applied |
| cancel_bulk_message_deletion | A bulk message deletion an account scheduled for itself was canceled |
| cancel_deletion | A scheduled account deletion was canceled |
| cancel_job | Cancellation of a job was requested |
| change_dob | A date of birth was changed |
| change_email | An email address was changed |
| change_username | A username or discriminator was changed |
| clear_fields | Profile fields of an account, or fields of a guild, were cleared |
| clear_report_legal_hold | The legal hold on a report was cleared |
| clear_role_icon | The icon of a guild role was cleared |
| create_admin_api_key | An Admin API key was created |
| create_badge | A custom badge was made |
| create_password_reset_link | A password reset link was created for an account |
| create_registration_url | A registration URL was issued |
| create_sign_in_link | A sign-in link was created for an admin account |
| create_user | An account was created by an Admin |
| create_voice_join_token | A voice join token was created |
| create_voice_region | A voice region was created |
| create_voice_server | A voice server was registered |
| create_voice_server_test_token | A test token for a voice server was signed |
| delete_all_user_messages | Deletion of every message an account sent was queued |
| delete_all_user_messages_dry_run | Deletion of every message an account sent was previewed with dry_run, and nothing was deleted |
| delete_badge | A custom badge was deleted |
| delete_guild | A guild was deleted |
| delete_message | One message was deleted |
| delete_report | A report was deleted with its stored evidence |
| delete_thread | A thread was deleted |
| delete_voice_region | A voice region was deleted |
| delete_voice_server | A registered voice server was deleted |
| delete_webauthn_credential | A WebAuthn credential was removed from an account |
| disable_mfa | Multi-factor authentication was disabled on an account |
| end_enforcement_decision | An enforcement decision was ended as lifted or reversed |
| force_add_to_guild | An account was added to a guild while bypassing the ban check |
| generate_gift_codes | Gift codes were generated |
| hide_built_in_badge | A built-in community badge was hidden on this instance |
| kick_member | A member was removed from a guild |
| limit_features | A feature limit decision was recorded for an account |
| link_sso_identity | A single sign-on subject was bound to an account by hand |
| migrate_sso_identities | Single sign-on subjects were moved from an earlier provider ID to the provider in use |
| move_badge | One custom badge was moved in the display order |
| preview_message_shred | The messages a shred would delete were listed |
| purge_asset | A stored media asset was purged |
| purge_guild_emoji_asset | A guild emoji asset was purged |
| purge_guild_sticker_asset | A guild sticker asset was purged |
| queue_bulk_job | A bulk job was queued |
| queue_message_shred | A message shred job was queued |
| queue_refresh_index | A search index rebuild was requested |
| reject_discovery_application | A discovery application was rejected |
| reject_registration | A pending registration was rejected |
| reload_guild | One guild was reloaded on the main Gateway |
| reload_guilds | Many guilds were reloaded on the main Gateway |
| remove_discovery_listing | A guild was removed from discovery |
| remove_relationship | One relationship was removed from an account |
| remove_registration_url | A revoked registration URL was removed from the list |
| remove_relationships_by_category | Every relationship in one category was removed from an account |
| rename_registration_url | A registration URL was given a new label |
| reorder_badges | The display order of the custom badges was changed |
| replace_built_in_badge_image | The image of a built-in badge was replaced |
| resend_verification_email | An email verification message was requested again for an account |
| reset_built_in_badge_image | A built-in badge went back to its built-in image |
| resolve_report | A report was updated or resolved |
| revoke_admin_api_key | An Admin API key was revoked |
| revoke_recovery_kit | The recovery kit of an account was revoked |
| revoke_registration_url | A registration URL was revoked |
| revoke_voice_join_token | A voice join token was revoked |
| schedule_deletion | Account deletion was scheduled |
| send_password_reset | A password reset message was requested for an account |
| set_acls | The Admin ACL set of an account was replaced |
| set_bot_status | The bot flag of an account was changed |
| set_report_legal_hold | A legal hold was placed on a report |
| set_system_status | The system flag of an account was changed |
| set_traits | Account traits were replaced |
| shutdown_guild | One guild was stopped on the main Gateway |
| show_built_in_badge | A hidden built-in community badge was shown again |
| system_dm.send | A system DM broadcast was created |
| temp_ban | An account was suspended for a time or permanently |
| terminate_sessions | Every login session of an account was revoked |
| test_smtp_connection | An SMTP connection test was run |
| transfer_ownership | Ownership of a guild or an OAuth2 application was transferred |
| trigger_guild_archive | A guild archive was created |
| trigger_user_archive | A user archive was created |
| unban | A suspension without an enforcement decision was lifted |
| unban_avatar_hash | An avatar hash was removed from the avatar blocklist |
| unban_email | An address was removed from the email blocklist |
| unban_file_sha | A file hash was removed from the attachment blocklist |
| unban_ip | An address was removed from the IP blocklist |
| unban_member | A guild ban was removed |
| unban_phrase | A phrase was removed from the message phrase blocklist |
| unban_profile_substring | A substring was removed from the profile substring blocklist |
| unban_url | A URL was removed from the URL blocklist |
| unban_url_domain | A domain was removed from the URL domain blocklist |
| unlink_sso_identities | The single sign-on subjects of an account were released |
| update_admin_api_key | An Admin API key was renamed or its ACLs were replaced |
| update_badge | A custom badge was updated |
| update_badge_settings | The limits on how many custom badges an account or guild can have were changed |
| update_discovery_categories | Guilds were moved to a discovery category |
| update_discovery_listing | A discovery listing was edited |
| update_features | Guild features were added or removed |
| update_flags | Account flags were changed |
| update_guild | A guild update changed none of the fields that have their own action |
| update_guild_badges | The custom badges of a guild were replaced |
| update_instance_config | The instance configuration was updated |
| update_limit_config | The limit configuration was replaced |
| update_name | A guild name was changed |
| update_premium_flags | Premium flags were changed |
| update_settings | General guild settings were changed |
| update_user_badges | The custom badges of an account were replaced |
| update_vanity | A guild custom invite code was changed |
| update_voice_region | A voice region was updated |
| update_voice_server | A registered voice server was updated |
| upload_branding_asset | An instance branding asset was uploaded or cleared |
| use_sign_in_link | An admin signed in with a sign-in link |
| verify_email | An email address was marked verified |
| warn_user | A warning decision was recorded for an account |
Audit reasons
Section titled “Audit reasons”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.
Errors and rate limits
Section titled “Errors and rate limits”Error response
Section titled “Error response”An Admin error uses the same format as the HTTP API error response.
These errors can come from any Admin route.
| Status | Body | Condition |
|---|---|---|
| 400 | error response | INVALID_FORM_BODY when the path, query or body is invalid |
| 401 | error response | UNAUTHORIZED when the credential is missing, invalid or a bot token |
| 403 | error response | ACCESS_DENIED for an access token from an OAuth2 application other than Admin |
| 403 | error response | MISSING_PERMISSIONS when the account holds neither admin:authenticate nor * |
| 403 | error response | MISSING_ACL when the caller holds none of the route's ACLs |
| 429 | error response | RATE_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.
List ACLs
Section titled “List ACLs”GET/v1/admin/aclsReturns every value in the ACL registry. You need admin:authenticate.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| acls | array[string] | The ACL registry, the same for every caller |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The registry was returned |
Records a list_admin_acls audit entry.
The rate limit is 200 requests per minute, on the admin:lookup bucket.
List audit log entries
Section titled “List audit log entries”GET/v1/admin/audit-logsReturns a page of Admin audit entries, newest first by default. You need audit_log:view.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| q? | string | Search action, target_type, target_id and audit_log_reason (1-1,024 characters) |
| admin_user_id? | snowflake | Only entries by this acting account |
| target_type? | string | Only entries with this target type (1-64 characters) |
| target_id? | string | Only entries with this target ID |
| access? | string | read or write |
| sort_by? | string | createdAt or relevance, used only with q (default createdAt) |
| sort_order? | string | asc or desc, used only with q (default desc) |
| limit? | integer | The maximum number of entries to return (1-200, default 50) |
| offset? | integer | The 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.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| logs | array[Admin audit entry object] | The entries in this page |
| total | integer | The number of entries that match |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The 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 audit log entry
Section titled “Get audit log entry”GET/v1/admin/audit-logs/{log_id}Returns one Admin audit entry. You need audit_log:view.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | Admin audit entry object | The entry was returned |
| 404 | error response | NOT_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.