Admin messages

Admin message routes browse, search and permanently delete the messages of one channel, and report the progress of shred jobs. To shred or delete all of a user's messages, use Shred user messages.

Admin message object

One message with its author, content, attachments and the NSFW settings of its channel and guild. Every response that returns Admin message objects also returns the matching public message objects in message_responses, in the same order.

Structure

Field	Type	Description
id	snowflake	The ID of the message
channel_id	snowflake	The channel the message was sent in
channel_name¹	?string	The channel name, or null when it has none
channel_nsfw¹	?boolean	Whether the channel is marked NSFW
channel_content_warning_level?²	?integer	The channel content warning level
channel_content_warning_text?²	?string	The channel content warning text (0-200 characters)
guild_id¹	?snowflake	The guild containing the channel, or null for a private channel
guild_name¹	?string	The guild name, or null for a private channel
guild_nsfw_level¹	?integer	The guild NSFW level, or null for a private channel
guild_nsfw?²	?boolean	Whether the guild is marked NSFW
guild_content_warning_level?²	?integer	The guild content warning level
guild_content_warning_text?²	?string	The guild content warning text (0-200 characters)
author_id	snowflake	The ID of the author
author_username	string	The author username (1-100 characters)
author_global_name	?string	The author display name, or null when unset
author_discriminator	string	The author discriminator tag (1-10 characters)
author_avatar	?string	The author avatar hash, or null when unset
author_bot?	boolean	Whether the author is a bot
webhook_id?	?snowflake	The ID of the webhook that sent the message, or null when a user sent it
content	string	The message content (0-4,000 characters)
timestamp	ISO8601 timestamp	When the message was sent
attachments	array[Admin message attachment object]	The attachments of the message (at most 10)
embeds?	array[embed object]	The embeds of the message

¹ These come from the channel in the request and are the same on every object in one response. All are null when the channel no longer exists

² Only the report message context object returns it. The routes on this page never do

Example

{
  "id": "1502771119476146176",
  "channel_id": "1471002884199612420",
  "channel_name": "general",
  "channel_nsfw": false,
  "guild_id": "1471002884199612416",
  "guild_name": "Tidepool",
  "guild_nsfw_level": 0,
  "author_id": "1490118377238528000",
  "author_username": "kestrel",
  "author_global_name": null,
  "author_discriminator": "0117",
  "author_avatar": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "content": "read the pinned message",
  "timestamp": "2026-03-04T18:19:07.220Z",
  "attachments": []
}

Admin message attachment object

Structure

Field	Type	Description
id	snowflake	The ID of the attachment
filename	string	The attachment filename (1-256 characters)
url	string	The CDN URL of the attachment (1-2,048 characters)
nsfw	?boolean	Whether the attachment is marked NSFW, or null when it has no marking
content_type	?string	The recorded MIME type, or null when none was recorded
width	?integer	The pixel width, or null when none was recorded
height	?integer	The pixel height, or null when none was recorded
size?	?integer	The size in bytes, or null when none was recorded

Message shred status object

The state of one message shred job. A job expires one hour after its last update. A job that is unknown, expired or not yet started by a worker returns only status, set to not_found.

Structure

Field	Type	Description
status	not_found \| in_progress \| completed \| failed	The job state
requested	integer	The number of message references the job was queued with
total	integer	The number of those references the job resolved as shreddable
processed	integer	The number of messages shredded so far
skipped	integer	The number of references the job did not shred
started_at?	ISO8601 timestamp	When the job started
completed_at?	ISO8601 timestamp	When the job completed
failed_at?	ISO8601 timestamp	When the job failed
error?¹	string	Why the job failed (1-4,000 characters)

¹ Present only when status is failed

List channel messages

GET/v1/admin/channels/{channel_id}/messages

Audit reason

Returns one page of Admin message objects for a channel, including messages that channel permissions hide from members. Needs message:lookup. An unknown channel returns an empty page.

Query parameters

Field	Type	Description
limit?	integer	Maximum messages to return (1-100, default 50)
before?¹	snowflake	Return messages with a lower ID than this cursor
after?¹	snowflake	Return messages with a higher ID than this cursor

¹ With neither, the page has the newest messages

Response body

Field	Type	Description
messages¹	array[Admin message object]	Messages in this page (at most 100)
message_responses?	array[message object]	The same messages as public message objects (at most 100)
has_more²	boolean	Whether the page was filled to `limit`

¹ Oldest first, or newest first when you sent after

² The next page can still be empty

Response

Status	Body	Condition
200	response body	Message page was returned

To page further, send the oldest returned ID as before or the newest as after.

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

Get message

GET/v1/admin/channels/{channel_id}/messages/{message_id}

Audit reason

Returns a message and the messages around it, oldest first. Needs message:lookup. An unknown message returns the window around where it would be, and an unknown channel returns an empty array.

Query parameters

Field	Type	Description
context_limit?	integer	Size of the whole window including the message (1-100, default 50)

Response body

Field	Type	Description
messages	array[Admin message object]	The message and its surrounding window (at most 100)
message_responses?	array[message object]	The same messages as public message objects (at most 100)
message_id	?snowflake	The requested message ID

Response

Status	Body	Condition
200	response body	Window was returned

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

Delete message

DELETE/v1/admin/channels/{channel_id}/messages/{message_id}

Audit reason

Permanently deletes one message and its attachments. Needs message:delete. Use it to clean up webhook or system messages, or for a holder request. To remove a message for breaking a rule, shred it with the enforcement basis.

JSON body

Field	Type	Description
basis	basis object	`holder_request` or `housekeeping`

Response body

Field	Type	Description
success	boolean	Always true

Response

Status	Body	Condition
200	response body	The request completed, even for an unknown channel or message

Fluxer sends Message Delete to the guild, or to each recipient in a private channel.

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

Search messages

GET/v1/admin/messages

Audit reason

Searches the messages of one channel, or looks up one message by message ID or attachment ID. Needs message:lookup. A request with message_id or attachment_id returns the lookup body and any other request returns the search body.

Query parameters

Field	Type	Description
channel_id	snowflake	The channel to search or look up in
q?	string	Free-text query on message content (1-200 characters)
message_id?¹	snowflake	Look up this message and its surrounding window
attachment_id?¹ ²	snowflake	Look up the message with this attachment and its surrounding window
filename?²	string	The exact filename of the attachment (1-255 characters)
context_limit?	integer	Window size for a lookup (1-100, default 50)
limit?	integer	Maximum messages to return when searching (1-100, default 25)

¹ message_id takes precedence over attachment_id, and attachment_id over q

² attachment_id needs filename, or the request fails with INVALID_FORM_BODY on filename

Search response body

Field	Type	Description
messages	array[Admin message object]	Matching messages (at most 100)
message_responses?	array[message object]	The same messages as public message objects (at most 100)
total	integer	The number of matching messages

Lookup response body

This is the body Get message returns.

Field	Type	Description
messages	array[Admin message object]	The resolved message and its surrounding window, oldest first (at most 100)
message_responses?	array[message object]	The same messages as public message objects (at most 100)
message_id¹	?snowflake	The ID of the resolved message

¹ Null only when an attachment lookup matches nothing

Response

Status	Body	Condition
200	search or lookup response body	Search or lookup completed, with empty results when nothing matches

Search has no pagination and returns at most limit matches. On an instance without message search set up, it returns no messages and a total of 0.

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

Get message shred job

GET/v1/admin/messages/shreds/{job_id}

Audit reason

Returns the message shred status of a job that Shred user messages or Delete all user messages started. Needs message:shred.

Response

Status	Body	Condition
200	message shred status object	Job state was returned

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