post/search/messages

Search messages

Searches for messages across guilds and channels accessible to the authenticated user. Bots must supply a context guild or channel and may only use the current scope.

search_messages

Request body

application/json

json

{
  "type": "object",
  "properties": {
    "hits_per_page": {
      "default": 25,
      "description": "Number of results per page (1-25)",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "page": {
      "default": 1,
      "description": "Page number for pagination (ignored when cursor is provided). Use cursor to page beyond this.",
      "type": "integer",
      "minimum": 1,
      "maximum": 400
    },
    "cursor": {
      "description": "Opaque cursor for search_after pagination. When provided, page is ignored.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "max_id": {
      "description": "Maximum message ID to include in results",
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "min_id": {
      "description": "Minimum message ID to include in results",
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "content": {
      "description": "Text content to search for",
      "type": "string"
    },
    "contents": {
      "description": "Multiple content queries to search for",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "exact_phrases": {
      "description": "Exact phrases that must appear contiguously in message content",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "channel_id": {
      "description": "Channel IDs to search in",
      "maxItems": 500,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      }
    },
    "exclude_channel_id": {
      "description": "Channel IDs to exclude from search",
      "maxItems": 500,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      }
    },
    "author_type": {
      "description": "Author types to filter by",
      "maxItems": 20,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageAuthorType"
      }
    },
    "exclude_author_type": {
      "description": "Author types to exclude",
      "maxItems": 20,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageAuthorType"
      }
    },
    "author_id": {
      "description": "Author user IDs to filter by",
      "maxItems": 100,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      }
    },
    "exclude_author_id": {
      "description": "Author user IDs to exclude",
      "maxItems": 100,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      }
    },
    "mentions": {
      "description": "User IDs that must be mentioned",
      "maxItems": 100,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      }
    },
    "exclude_mentions": {
      "description": "User IDs that must not be mentioned",
      "maxItems": 100,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      }
    },
    "mention_everyone": {
      "description": "Filter by whether message mentions everyone",
      "type": "boolean"
    },
    "pinned": {
      "description": "Filter by pinned status",
      "type": "boolean"
    },
    "has": {
      "description": "Content flags the message must have. Use image, video, sound, or file for uploaded attachments and embed for link previews or rich embeds.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageContentType"
      }
    },
    "exclude_has": {
      "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.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageContentType"
      }
    },
    "embed_type": {
      "description": "Generated or supplied embed types to filter by; does not match uploaded attachments",
      "maxItems": 20,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageEmbedType"
      }
    },
    "exclude_embed_type": {
      "description": "Generated or supplied embed types to exclude; does not match uploaded attachments",
      "maxItems": 20,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageEmbedType"
      }
    },
    "embed_provider": {
      "description": "Embed providers to filter by",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "exclude_embed_provider": {
      "description": "Embed providers to exclude",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "link_hostname": {
      "description": "Link hostnames to filter by",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "exclude_link_hostname": {
      "description": "Link hostnames to exclude",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "attachment_filename": {
      "description": "Attachment filenames to filter by",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "exclude_attachment_filename": {
      "description": "Attachment filenames to exclude",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "attachment_extension": {
      "description": "File extensions to filter by",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "exclude_attachment_extension": {
      "description": "File extensions to exclude",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "sort_by": {
      "default": "timestamp",
      "description": "Field to sort results by",
      "$ref": "#/components/schemas/MessageSortField"
    },
    "sort_order": {
      "default": "desc",
      "description": "Sort order for results",
      "$ref": "#/components/schemas/MessageSortOrder"
    },
    "include_nsfw": {
      "default": false,
      "description": "Whether to include NSFW channel results",
      "type": "boolean"
    },
    "scope": {
      "description": "Scope to search within when querying messages",
      "$ref": "#/components/schemas/MessageSearchScope"
    },
    "context_channel_id": {
      "description": "Channel ID for context when searching across multiple channels",
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "context_guild_id": {
      "description": "Guild ID for context when searching across multiple guilds",
      "$ref": "#/components/schemas/SnowflakeType"
    },
    "channel_ids": {
      "description": "Specific channel IDs to search in",
      "maxItems": 500,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      }
    }
  }
}

Responses

200

Success

json

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

400

Bad Request - The request was malformed or contained invalid data

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}

401

Unauthorized - Authentication is required or the token is invalid

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}

403

Forbidden - You do not have permission to perform this action

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}

429

Too Many Requests - You are being rate limited

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    },
    "retry_after": {
      "type": "number",
      "description": "Seconds to wait before retrying"
    },
    "global": {
      "type": "boolean",
      "description": "Whether this is a global rate limit"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}

500

Internal Server Error - An unexpected error occurred

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}