Skip to content
Modrinth Documentation

Search projects

GET
/search

Parameters

Query Parameters

query
string
gravestones

The query to search for

facets
string

Facets are an essential concept for understanding how to filter out results.

These are the most commonly used facet types:

  • project_type
  • categories (loaders are lumped in with categories in search)
  • versions
  • client_side
  • server_side
  • open_source

Several others are also available for use, though these should not be used outside very specific use cases.

  • title
  • author
  • follows
  • project_id
  • license
  • downloads
  • color
  • created_timestamp
  • modified_timestamp

In order to then use these facets, you need a value to filter by, as well as an operation to perform on this value. The most common operation is : (same as =), though you can also use !=, >=, >, <=, and <. Join together the type, operation, and value, and you’ve got your string.

{type} {operation} {value}

Examples:

categories = adventure
versions != 1.20.1
downloads <= 100

You then join these strings together in arrays to signal AND and OR operators.

OR

All elements in a single array are considered to be joined by OR statements. For example, the search [["versions:1.16.5", "versions:1.17.1"]] translates to Projects that support 1.16.5 OR 1.17.1.

AND

Separate arrays are considered to be joined by AND statements. For example, the search [["versions:1.16.5"], ["project_type:modpack"]] translates to Projects that support 1.16.5 AND are modpacks.

Example
[["categories:forge"],["versions:1.17.1"],["project_type:mod"],["license:mit"]]
index
string
default: relevance
Allowed values: relevance downloads follows newest updated 
downloads

The sorting method used for sorting search results

offset
integer
20

The offset into the search. Skips this number of results

limit
integer
default: 10 <= 100 
20

The number of results returned by the search

Responses

200

Expected response to a valid request

object
hits
required

The list of results

Array
object
project_id
required

The ID of the project

string
AABBCCDD
author
required

The username of the project’s author

string
my_user
display_categories

A list of the categories that the project has which are not secondary

Array<string>
[
  "technology",
  "fabric"
]
versions
required

A list of the minecraft versions supported by the project

Array<string>
[
  "1.8",
  "1.8.9"
]
follows
required

The total number of users following the project

integer
date_created
required

The date the project was added to search

string format: ISO-8601
date_modified
required

The date the project was last modified

string format: ISO-8601
latest_version

The latest version of minecraft that this project supports

string
1.8.9
license
required

The SPDX license ID of a project

string
MIT
gallery

All gallery images attached to the project

Array<string>
[
  "https://cdn.modrinth.com/data/AABBCCDD/images/009b7d8d6e8bf04968a29421117c59b3efe2351a.png",
  "https://cdn.modrinth.com/data/AABBCCDD/images/c21776867afb6046fdc3c21dbcf5cc50ae27a236.png"
]
featured_gallery

The featured gallery image of the project

string
nullable
offset
required

The number of results that were skipped by the query

integer
0
limit
required

The number of results that were returned by the query

integer
10
total_hits
required

The total number of results that match the query

integer
10

400

Request was invalid, see given error

object
error
required

The name of the error

string
invalid_input
description
required

The contents of the error

string
Error while parsing multipart payload