Skip to main content

​
Overview

The Modrinth search API allows you to search for projects (mods, modpacks, resource packs, etc.) with advanced filtering, faceting, and sorting capabilities powered by MeiliSearch.

​
Search Endpoint

Search for projects with optional query parameters for filtering and pagination.

​
Query Parameters

​
string
Search query string. Searches across project names, descriptions, and authors.Example: fabric optimization
​
integer
default:"10"
Number of results to return per page. Maximum value is 100.Example: 20
​
integer
default:"0"
Number of results to skip for pagination.Example: 40
​
string
default:"relevance"
The sorting method to use for results.Available values:
  • relevance - Sort by relevance (default)
  • downloads - Sort by download count
  • follows - Sort by follower count
  • newest or date_created - Sort by creation date
  • updated or date_modified - Sort by last update date
Example: downloads
​
string
Advanced filter string using MeiliSearch filter syntax. This is the recommended way to filter results.Example: project_types=["mod"] AND categories=["optimization"]
​
string
Deprecated - Use new_filters instead. JSON-encoded array for faceted search.Facets allow for complex AND/OR filter combinations:
  • Outer array = AND
  • Inner array = OR
  • Innermost array (optional) = AND
Example: [["categories:fabric"], ["project_type:mod"]]
​
string
Deprecated - Use new_filters instead. Additional filter string.
​
string
Deprecated - Use new_filters instead. Version-specific filter.

​
Filter Syntax

The new_filters parameter supports MeiliSearch filter syntax with the following operators:

​
Comparison Operators

  • = - Equals
  • != - Not equals
  • >, >=, <, <= - Comparison (for numbers)
  • IN [...] - Value in array
  • NOT IN [...] - Value not in array

​
Logical Operators

  • AND - Logical AND
  • OR - Logical OR
  • () - Grouping

​
Filterable Fields

  • project_types - Array of project types (mod, modpack, resourcepack, etc.)
  • categories - Array of category names
  • loaders - Array of loader names (fabric, forge, quilt, etc.)
  • game_versions - Array of game versions
  • project_id - Project ID
  • author - Author username
  • license - License identifier
  • open_source - Boolean for open source status
  • downloads - Download count (number)
  • follows - Follower count (number)
  • created_timestamp - Unix timestamp of creation
  • modified_timestamp - Unix timestamp of last modification
For Minecraft Java servers:
  • minecraft_java_server.content.kind - Content type (vanilla, modded, etc.)
  • minecraft_java_server.verified_plays_2w - Verified plays in last 2 weeks
  • minecraft_java_server.ping.data.players_online - Current players online
Note: components. prefix is automatically normalized and removed.

​
Examples

​
Search with Filters

​
Search by Downloads

​
Complex Filter Example

​
Pagination Example

​
Response Format

​
array
Array of project search results.
​
integer
Current page number (calculated from offset and limit)
​
integer
Number of results per page
​
integer
Total number of matching results

​
Search Tips

  • Use specific queries when possible to reduce result set
  • Leverage filters instead of broad queries
  • Keep limit reasonable (10-50 for most use cases)
  • Use appropriate sorting index for your needs
Faceted search allows you to combine multiple filters with AND/OR logic:
The outer array combines with AND, inner arrays with OR, and optional innermost arrays with AND.
When filtering Minecraft Java server components, the components. prefix is automatically removed:
  • components.minecraft_java_server.content = vanilla becomes minecraft_java_server.content.kind = vanilla
This normalization happens automatically in the filter parsing.