v19

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-037759134.1 KB

projects

Search projects

get/search

Query parameters

querystring

Example:gravestones

The query to search for

facetsstring

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
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
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.

index'relevance' | 'downloads' | 'follows' | 'newest' | 'updated'

Example:downloads

The sorting method used for sorting search results

offsetinteger

Example:20

The offset into the search. Skips this number of results

limitinteger

Example:20

The number of results returned by the search

Response

Expected response to a valid request

offsetinteger required

The number of results that were skipped by the query

limitinteger required

The number of results that were returned by the query

total_hitsinteger required

The total number of results that match the query

Example response

{
  "hits": [
    {
      "slug": "my_project",
      "title": "My Project",
      "description": "A short description",
      "categories": [
        "technology",
        "adventure",
        "fabric"
      ],
      "client_side": "required",
      "server_side": "optional",
      "project_type": "mod",
      "icon_url": "https://cdn.modrinth.com/data/AABBCCDD/b46513nd83hb4792a9a0e1fn28fgi6090c1842639.png",
      "color": 8703084,
      "thread_id": "TTUUVVWW",
      "project_id": "AABBCCDD",
      "all_project_types": [
        "mod",
        "plugin",
        "datapack"
      ],
      "author": "my_user",
      "display_categories": [
        "technology",
        "fabric"
      ],
      "versions": [
        "1.8",
        "1.8.9"
      ],
      "latest_version": "1.8.9",
      "license": "MIT",
      "gallery": [
        "https://cdn.modrinth.com/data/AABBCCDD/images/009b7d8d6e8bf04968a29421117c59b3efe2351a.png",
        "https://cdn.modrinth.com/data/AABBCCDD/images/c21776867afb6046fdc3c21dbcf5cc50ae27a236.png"
      ]
    }
  ],
  "limit": 10,
  "total_hits": 10
}

All 77 operations