post/search/messages

Search messages

Searches for messages across guilds and channels accessible to the authenticated user.

search_messages

Request body

application/json

json

{
  "type": "object",
  "properties": {
    "hits_per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "format": "int32",
      "description": "Number of results per page (1-25)"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "format": "int53",
      "description": "Page number for pagination (ignored when cursor is provided)"
    },
    "cursor": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Opaque cursor for search_after pagination. When provided, page is ignored."
    },
    "max_id": {
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "min_id": {
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "content": {
      "type": "string",
      "description": "Text content to search for"
    },
    "contents": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "description": "Multiple content queries to search for"
    },
    "exact_phrases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "description": "Exact phrases that must appear contiguously in message content"
    },
    "channel_id": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 500,
      "description": "Channel IDs to search in"
    },
    "exclude_channel_id": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 500,
      "description": "Channel IDs to exclude from search"
    },
    "author_type": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "user",
          "bot",
          "webhook"
        ],
        "x-enumNames": [
          "user",
          "bot",
          "webhook"
        ],
        "x-enumDescriptions": [
          "A regular user account",
          "An automated bot account",
          "A webhook-generated message"
        ],
        "description": "The type of author who sent the message"
      },
      "maxItems": 20,
      "description": "Author types to filter by"
    },
    "exclude_author_type": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "user",
          "bot",
          "webhook"
        ],
        "x-enumNames": [
          "user",
          "bot",
          "webhook"
        ],
        "x-enumDescriptions": [
          "A regular user account",
          "An automated bot account",
          "A webhook-generated message"
        ],
        "description": "The type of author who sent the message"
      },
      "maxItems": 20,
      "description": "Author types to exclude"
    },
    "author_id": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 100,
      "description": "Author user IDs to filter by"
    },
    "exclude_author_id": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 100,
      "description": "Author user IDs to exclude"
    },
    "mentions": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 100,
      "description": "User IDs that must be mentioned"
    },
    "exclude_mentions": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 100,
      "description": "User IDs that must not be mentioned"
    },
    "mention_everyone": {
      "type": "boolean",
      "description": "Filter by whether message mentions everyone"
    },
    "pinned": {
      "type": "boolean",
      "description": "Filter by pinned status"
    },
    "has": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "image",
          "sound",
          "video",
          "file",
          "sticker",
          "embed",
          "link",
          "poll",
          "snapshot"
        ],
        "x-enumNames": [
          "image",
          "sound",
          "video",
          "file",
          "sticker",
          "embed",
          "link",
          "poll",
          "snapshot"
        ],
        "x-enumDescriptions": [
          "Message contains an uploaded image attachment; linked image previews are embeds",
          "Message contains an uploaded audio attachment; linked audio previews are embeds",
          "Message contains an uploaded video attachment; linked video previews are embeds",
          "Message contains at least one uploaded attachment of any type",
          "Message contains a sticker",
          "Message contains a generated link preview or rich embed; uploads are attachments",
          "Message text contains a typed URL link",
          "Message contains a poll",
          "Message contains a forwarded message snapshot"
        ],
        "description": "The type of content contained in a message. Upload filters inspect attachments; embed filters inspect generated or supplied message embeds."
      },
      "maxItems": 20,
      "description": "Content flags the message must have. Use image, video, sound, or file for uploaded attachments and embed for link previews or rich embeds."
    },
    "exclude_has": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "image",
          "sound",
          "video",
          "file",
          "sticker",
          "embed",
          "link",
          "poll",
          "snapshot"
        ],
        "x-enumNames": [
          "image",
          "sound",
          "video",
          "file",
          "sticker",
          "embed",
          "link",
          "poll",
          "snapshot"
        ],
        "x-enumDescriptions": [
          "Message contains an uploaded image attachment; linked image previews are embeds",
          "Message contains an uploaded audio attachment; linked audio previews are embeds",
          "Message contains an uploaded video attachment; linked video previews are embeds",
          "Message contains at least one uploaded attachment of any type",
          "Message contains a sticker",
          "Message contains a generated link preview or rich embed; uploads are attachments",
          "Message text contains a typed URL link",
          "Message contains a poll",
          "Message contains a forwarded message snapshot"
        ],
        "description": "The type of content contained in a message. Upload filters inspect attachments; embed filters inspect generated or supplied message embeds."
      },
      "maxItems": 20,
      "description": "Content flags the message must not have. Use image, video, sound, or file for uploaded attachments and embed for link previews or rich embeds."
    },
    "embed_type": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "image",
          "video",
          "sound",
          "article"
        ],
        "x-enumNames": [
          "image",
          "video",
          "sound",
          "article"
        ],
        "x-enumDescriptions": [
          "An image preview from a linked URL or embed object; uploaded images use the image content flag",
          "A video preview from a linked URL or embed object; uploaded videos use the video content flag",
          "An audio preview from a linked URL or embed object; uploaded audio uses the sound content flag",
          "An article or webpage preview with metadata"
        ],
        "description": "The type of generated or supplied embed content, not uploaded attachments"
      },
      "maxItems": 20,
      "description": "Generated or supplied embed types to filter by; does not match uploaded attachments"
    },
    "exclude_embed_type": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "image",
          "video",
          "sound",
          "article"
        ],
        "x-enumNames": [
          "image",
          "video",
          "sound",
          "article"
        ],
        "x-enumDescriptions": [
          "An image preview from a linked URL or embed object; uploaded images use the image content flag",
          "A video preview from a linked URL or embed object; uploaded videos use the video content flag",
          "An audio preview from a linked URL or embed object; uploaded audio uses the sound content flag",
          "An article or webpage preview with metadata"
        ],
        "description": "The type of generated or supplied embed content, not uploaded attachments"
      },
      "maxItems": 20,
      "description": "Generated or supplied embed types to exclude; does not match uploaded attachments"
    },
    "embed_provider": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 50,
      "description": "Embed providers to filter by"
    },
    "exclude_embed_provider": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 50,
      "description": "Embed providers to exclude"
    },
    "link_hostname": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "description": "Link hostnames to filter by"
    },
    "exclude_link_hostname": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "description": "Link hostnames to exclude"
    },
    "attachment_filename": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "description": "Attachment filenames to filter by"
    },
    "exclude_attachment_filename": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "description": "Attachment filenames to exclude"
    },
    "attachment_extension": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 50,
      "description": "File extensions to filter by"
    },
    "exclude_attachment_extension": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 50,
      "description": "File extensions to exclude"
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "timestamp",
        "relevance"
      ],
      "x-enumNames": [
        "timestamp",
        "relevance"
      ],
      "x-enumDescriptions": [
        "Sort results by message timestamp",
        "Sort results by search relevance score"
      ],
      "description": "Field to sort results by"
    },
    "sort_order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "x-enumNames": [
        "asc",
        "desc"
      ],
      "x-enumDescriptions": [
        "Sort in ascending order (oldest/lowest first)",
        "Sort in descending order (newest/highest first)"
      ],
      "description": "Sort order for results"
    },
    "include_nsfw": {
      "type": "boolean",
      "description": "Whether to include NSFW channel results"
    },
    "scope": {
      "type": "string",
      "enum": [
        "current",
        "open_dms",
        "all_dms",
        "all_guilds",
        "all",
        "open_dms_and_all_guilds"
      ],
      "x-enumNames": [
        "current",
        "open_dms",
        "all_dms",
        "all_guilds",
        "all",
        "open_dms_and_all_guilds"
      ],
      "x-enumDescriptions": [
        "Search only in the current channel or community context",
        "Search across all DMs you currently have open",
        "Search across all DMs you've ever been in",
        "Search across all Communities you're currently in",
        "Search across all DMs you've ever been in and all Communities you're currently in",
        "Search across all DMs you currently have open and all Communities you're currently in"
      ],
      "description": "Scope to search within when querying messages"
    },
    "context_channel_id": {
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "context_guild_id": {
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "channel_ids": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 500,
      "description": "Specific channel IDs to search in"
    }
  }
}

Responses

200

Success

json

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/MessageSearchResultsResponse"
    },
    {
      "type": "object",
      "properties": {
        "indexing": {
          "type": "boolean",
          "enum": [
            true
          ],
          "description": "Indicates that one or more channels are being indexed"
        }
      },
      "required": [
        "indexing"
      ]
    }
  ]
}

400

Bad Request - The request was malformed or contained invalid data

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

401

Unauthorized - Authentication is required or the token is invalid

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

403

Forbidden - You do not have permission to perform this action

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

429

Too Many Requests - You are being rate limited

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "RATE_LIMITED"
      ]
    },
    "message": {
      "type": "string"
    },
    "retry_after": {
      "type": "number",
      "description": "Seconds to wait before retrying"
    },
    "global": {
      "type": "boolean",
      "description": "Whether this is a global rate limit"
    }
  },
  "required": [
    "code",
    "message",
    "retry_after"
  ]
}

500

Internal Server Error - An unexpected error occurred

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}