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
  • all_project_types (matches against every project type across all of the project’s versions, not just the primary/version-specific type)
  • categories (loaders are lumped in with categories in search)
  • versions
  • open_source
  • environment (one of the following values)
    • client_and_server
    • client_only
    • client_only_server_optional
    • singleplayer_only
    • server_only
    • server_only_client_optional
    • dedicated_server_only
    • client_or_server
    • client_or_server_prefers_both
    • unknown
  • disclosure_types (list of any of the following values)
    • ai_content
    • ai_content_code
    • ai_content_assets
    • ai_content_text
    • ai_content_functionality
    • advertisements
    • epilepsy_triggers
    • system_interactions
    • telemetry
    • telemetry_opt_in
    • telemetry_opt_out
    • telemetry_always_active
    • derivative_work
    • paid_features
    • archived
  • client_side (deprecated - use environment instead)
  • server_side (deprecated - use environment instead)

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
  • created_timestamp (uses Unix timestamp)
  • modified_timestamp (uses Unix 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>
object
project_id
required

The ID of the project, encoded as a base62 string

string
AABBCCDD
project_type
required

The project type of the project

string
Allowed values: mod modpack resourcepack shader 
mod
all_project_types
required

All project types across every version of the project, unlike project_type which only reflects a version-specific type

Array<string>
Allowed values: mod resourcepack datapack shader modpack plugin 
[
  "mod",
  "plugin",
  "datapack"
]
title
required

The title or name of the project

string
description
required

A short sentence summarizing the project, no more than a sentence or two.

string
author
required

The username of the project’s author

string
my_user
categories
required

A list of the featured categories that the project has.

Array<string>
[
  "technology",
  "adventure",
  "fabric"
]
display_categories
required

A list of the featured categories that the project has. Equivalent to categories on the project itself.

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

A list of the minecraft versions supported by the project

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

The total number of downloads of the project

integer
follows
required

The total number of users following the project

integer
icon_url
required

The URL of the project’s icon

string
https://cdn.modrinth.com/data/AABBCCDD/b46513nd83hb4792a9a0e1fn28fgi6090c1842639.png
date_created
required

The date the project was created

string format: ISO-8601
date_modified
required

The date the latest version of the project was created

string format: ISO-8601
latest_version
required

The ID of the latest version of the project

string
IIJJKKLL
license
required

The SPDX license ID of a project

string
MIT
environment
required

All the environments that versions of this project support. Not in any particular order, we recommend using the environment information on a version instead. For an explanation of each environment, see the blog post here: https://modrinth.com/news/article/new-environments/#new-system

Array<string>
Allowed values: client_and_server client_only client_only_server_optional singleplayer_only server_only server_only_client_optional dedicated_server_only client_or_server client_or_server_prefers_both unknown 
[
  "client_and_server"
]
disclosure_types
required

Disclosures listed on the project.

Array<string>
Allowed values: ai_content ai_content_code ai_content_assets ai_content_text ai_content_functionality advertisements epilepsy_triggers system_interactions telemetry telemetry_opt_in telemetry_opt_out telemetry_always_active derivative_work paid_features archived 
[
  "ai_content",
  "ai_content_code",
  "advertisements"
]
gallery
required

A list of images that have been uploaded to the project’s gallery

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

The slug of a project, used for vanity URLs. Regex: ^[\w!@$()`.+,"\-']{3,64}$

string
nullable 
my_project
author_id

The ID of the project’s author

string
nullable 
EEFFGGHH
organization

The name of the organization that owns this project

string
nullable 
my_org
organization_id

The ID of the organization that owns this project

string
nullable 
AABBCCDD
featured_gallery

The featured gallery image of the project

string
nullable
color

The RGB color of the project, automatically generated from the project icon

integer
nullable 
8703084
client_side
required

Deprecated - use environment instead. The client side support of the project

string
Allowed values: required optional unsupported unknown 
required
server_side
required

Deprecated - use environment instead. The server side support of the project

string
Allowed values: required optional unsupported unknown 
optional
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