Searching projects is a common use case of the Modrinth API, but can be difficult to understand. By the end of this tutorial, you should have a high level understanding of how to search for projects using the API!
The search API is available at
In these examples, we'll be searching for a gravestones mod on Fabric 1.16.5.
The query is the text you want to search for. In this example, a query might be
grave. You can see what the API response is
The index field changes the way the results will be sorted in the response. Modrinth supports the following indexes:
relevance=> This sorts by the element that our system is the best match for your query, at least based on our query.
downloads=> This sorts all matches by the order of downloads.
follows=> The same principle as
downloads, but sorted by the number of followers of this mod.
newest=> Sorts by the newest mod created. This is based on the time of initial creation of the mod.
updated=> Sorts by the newest mod updated. This is based on the time of the latest update of the mod (creation of a new version).
The maximum number of results that will be returned in the response. The maximum limit is 100.
The offset field allows for projects to be skipped from the result. When combined with the limit parameter, the offset field can be used to create powerful pagination.
Facets are an essential concept for understanding how to filter out results.
A facet can be of multiple types:
categories=> The loader or category to filter the results from
versions=> The minecraft version to filter the results from
license=> The license ID to filter the results from
project_type=> The project type to filter the results from
Now you have all the facets types, to get a string representing both the type and the content, you have to use the following format:
Where type is one of the facet types defined above.
In search, the main operators are
OR. The others are not supported as of now.
All elements in a single array after the first one are considered in a single OR block.
For example, the search
[["versions:1.16.5", "versions:1.17.1"]] translates to
Projects that supports 1.16.5 OR 1.17.1
All arrays in the top-level one are considered in a single AND block.
For example, the search
[["versions:1.16.5"], ["project_type:modpack"]] translates to
Projects that support 1.16.5 AND are modpacks
If you want to learn more about facets, the documentation on them is available here
Here's an example query if you are confused on how to use facets:
This request searches for up to 20 projects sorted by relevance that are in the categories
fabric and that support 1.17.1.
Filters are an alternative way to facets to filter out results. Filters are slower than facets.
The syntax for filters can be found here.