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

GET /v3/search
Search for projects with optional query parameters for filtering and pagination.

​
Query Parameters

​
query
string
Search query string. Searches across project names, descriptions, and authors.Example: fabric optimization
​
limit
integer
default:"10"
Number of results to return per page. Maximum value is 100.Example: 20
​
offset
integer
default:"0"
Number of results to skip for pagination.Example: 40
​
index
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
​
new_filters
string
Advanced filter string using MeiliSearch filter syntax. This is the recommended way to filter results.Example: project_types=["mod"] AND categories=["optimization"]
​
facets
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"]]
​
filters
string
Deprecated - Use new_filters instead. Additional filter string.
​
version
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

curl "https://api.modrinth.com/v3/search?query=optimization&limit=10"

​
Search with Filters

curl "https://api.modrinth.com/v3/search?query=fabric&new_filters=project_types%3D%5B%22mod%22%5D%20AND%20categories%3D%5B%22optimization%22%5D&limit=20"

​
Search by Downloads

curl "https://api.modrinth.com/v3/search?index=downloads&limit=10"

​
Complex Filter Example

curl "https://api.modrinth.com/v3/search?new_filters=(project_types%3D%5B%22mod%22%5D%20OR%20project_types%3D%5B%22modpack%22%5D)%20AND%20loaders%3D%5B%22fabric%22%5D&index=downloads"

​
Pagination Example

curl "https://api.modrinth.com/v3/search?query=fabric&limit=20&offset=40"

​
Response Format

​
hits
array
Array of project search results.
​
page
integer
Current page number (calculated from offset and limit)
​
hits_per_page
integer
Number of results per page
​
total_hits
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
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.