Skip to main content
API docs by Redocly

Labrinth (v2.7.0/15cf3fc)

Download OpenAPI specification:Download

Modrinth Support: support@modrinth.com URL: https://support.modrinth.com Terms of Service

This documentation doesn't provide a way to test our API. In order to facilitate testing, we recommend the following tools:

  • cURL (recommended, command-line)
  • ReqBIN (recommended, online)
  • Postman
  • Insomnia
  • Your web browser, if you don't need to send headers or a request body

Once you have a working client, you can test that it works by making a GET request to https://staging-api.modrinth.com/:

{
  "about": "Welcome traveler!",
  "documentation": "https://docs.modrinth.com",
  "name": "modrinth-labrinth",
  "version": "2.7.0"
}

If you got a response similar to the one above, you can use the Modrinth API! When you want to go live using the production API, use api.modrinth.com instead of staging-api.modrinth.com.

Authentication

This API has two options for authentication: personal access tokens and OAuth2. All tokens are tied to a Modrinth user and use the Authorization header of the request.

Example:

Authorization: mrp_RNtLRSPmGj2pd1v1ubi52nX7TJJM9sznrmwhAuj511oe4t1jAqAQ3D6Wc8Ic

You do not need a token for most requests. Generally speaking, only the following types of requests require a token:

  • those which create data (such as version creation)
  • those which modify data (such as editing a project)
  • those which access private data (such as draft projects, notifications, emails, and payout data)

Each request requiring authentication has a certain scope. For example, to view the email of the user being requested, the token must have the USER_READ_EMAIL scope. You can find the list of available scopes on GitHub. Making a request with an invalid scope will return a 401 error.

Please note that certain scopes and requests cannot be completed with a personal access token or using OAuth. For example, deleting a user account can only be done through Modrinth's frontend.

OAuth2

Applications interacting with the authenticated API should create an OAuth2 application. You can do this in the developer settings.

Once you have created a client, use the following URL to have a user authorize your client:

https://modrinth.com/auth/authorize?client_id=<CLIENT_ID>&redirect_uri=<CALLBACK_URL>&scope=<SCOPE_ONE>+<SCOPE_TWO>+<SCOPE_THREE>

Then, use the following URL to get the token:

https://api.modrinth.com/_internal/oauth/token

This route will be changed in the future to move the _internal part to v3.

Personal access tokens

Personal access tokens (PATs) can be generated in from the user settings.

GitHub tokens

For backwards compatibility purposes, some types of GitHub tokens also work for authenticating a user with Modrinth's API, granting all scopes. We urge any application still using GitHub tokens to start using personal access tokens for security and reliability purposes. GitHub tokens will cease to function to authenticate with Modrinth's API as soon as version 3 of the API is made generally available.

Cross-Origin Resource Sharing

This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with the W3C spec. This allows for cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.

Identifiers

The majority of items you can interact with in the API have a unique eight-digit base62 ID. Projects, versions, users, threads, teams, and reports all use this same way of identifying themselves. Version files use the sha1 or sha512 file hashes as identifiers.

Each project and user has a friendlier way of identifying them; slugs and usernames, respectively. While unique IDs are constant, slugs and usernames can change at any moment. If you want to store something in the long term, it is recommended to use the unique ID.

Ratelimits

The API has a ratelimit defined per IP. Limits and remaining amounts are given in the response headers.

  • X-Ratelimit-Limit: the maximum number of requests that can be made in a minute
  • X-Ratelimit-Remaining: the number of requests remaining in the current ratelimit window
  • X-Ratelimit-Reset: the time in seconds until the ratelimit window resets

Ratelimits are the same no matter whether you use a token or not. The ratelimit is currently 300 requests per minute. If you have a use case requiring a higher limit, please contact us.

User Agents

To access the Modrinth API, you must use provide a uniquely-identifying User-Agent header. Providing a user agent that only identifies your HTTP client library (such as "okhttp/4.9.3") increases the likelihood that we will block your traffic. It is recommended, but not required, to include contact information in your user agent. This allows us to contact you if we would like a change in your application's behavior without having to block your traffic.

  • Bad: User-Agent: okhttp/4.9.3
  • Good: User-Agent: project_name
  • Better: User-Agent: github_username/project_name/1.56.0
  • Best: User-Agent: github_username/project_name/1.56.0 (launcher.com) or User-Agent: github_username/project_name/1.56.0 (contact@launcher.com)

Versioning

Modrinth follows a simple pattern for its API versioning. In the event of a breaking API change, the API version in the URL path is bumped, and migration steps will be published below.

When an API is no longer the current one, it will immediately be considered deprecated. No more support will be provided for API versions older than the current one. It will be kept for some time, but this amount of time is not certain.

We will exercise various tactics to get people to update their implementation of our API. One example is by adding something like STOP USING THIS API to various data returned by the API.

Once an API version is completely deprecated, it will permanently return a 410 error. Please ensure your application handles these 410 errors.

Migrations

Inside the following spoiler, you will be able to find all changes between versions of the Modrinth API, accompanied by tips and a guide to migrate applications to newer versions.

Here, you can also find changes for Minotaur, Modrinth's official Gradle plugin. Major versions of Minotaur directly correspond to major versions of the Modrinth API.

API v1 to API v2

These bullet points cover most changes in the v2 API, but please note that fields containing mod in most contexts have been shifted to project. For example, in the search route, the field mod_id was renamed to project_id.

  • The search route has been moved from /api/v1/mod to /v2/search
  • New project fields: project_type (may be mod or modpack), moderation_message (which has a message and body), gallery
  • New search facet: project_type
  • Alphabetical sort removed (it didn't work and is not possible due to limits in MeiliSearch)
  • New search fields: project_type, gallery
    • The gallery field is an array of URLs to images that are part of the project's gallery
  • The gallery is a new feature which allows the user to upload images showcasing their mod to the CDN which will be displayed on their mod page
  • Internal change: Any project file uploaded to Modrinth is now validated to make sure it's a valid Minecraft mod, Modpack, etc.
    • For example, a Forge 1.17 mod with a JAR not containing a mods.toml will not be allowed to be uploaded to Modrinth
  • In project creation, projects may not upload a mod with no versions to review, however they can be saved as a draft
    • Similarly, for version creation, a version may not be uploaded without any files
  • Donation URLs have been enabled
  • New project status: archived. Projects with this status do not appear in search
  • Tags (such as categories, loaders) now have icons (SVGs) and specific project types attached
  • Dependencies have been wiped and replaced with a new system
  • Notifications now have a type field, such as project_update

Along with this, project subroutes (such as /v2/project/{id}/version) now allow the slug to be used as the ID. This is also the case with user routes.

Minotaur v1 to Minotaur v2

Minotaur 2.x introduced a few breaking changes to how your buildscript is formatted.

First, instead of registering your own publishModrinth task, Minotaur now automatically creates a modrinth task. As such, you can replace the task publishModrinth(type: TaskModrinthUpload) { line with just modrinth {.

To declare supported Minecraft versions and mod loaders, the gameVersions and loaders arrays must now be used. The syntax for these are pretty self-explanatory.

Instead of using releaseType, you must now use versionType. This was actually changed in v1.2.0, but very few buildscripts have moved on from v1.1.0.

Dependencies have been changed to a special DSL. Create a dependencies block within the modrinth block, and then use scope.type("project/version"). For example, required.project("fabric-api") adds a required project dependency on Fabric API.

You may now use the slug anywhere that a project ID was previously required.

Projects

Projects are what Modrinth is centered around, be it mods, modpacks, resource packs, etc.

Search projects

query Parameters
query
string
Example: query=gravestones

The query to search for

facets
string
Example: facets=[["categories:forge"],["versions:1.17.1"],["project_type:mod"],["license:mit"]]

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.

index
string
Default: "relevance"
Enum: "relevance" "downloads" "follows" "newest" "updated"
Example: index=downloads

The sorting method used for sorting search results

offset
integer
Default: 0
Example: offset=20

The offset into the search. Skips this number of results

limit
integer [ 0 .. 100 ]
Default: 10
Example: limit=20

The number of results returned by the search

Responses

Response samples

Content type
application/json
{}

Get a project

path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{}

Modify a project

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Request Body schema: application/json

Modified project fields

slug
string

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

title
string

The title or name of the project

description
string

A short description of the project

categories
Array of strings

A list of the categories that the project has

client_side
string
Enum: "required" "optional" "unsupported" "unknown"

The client side support of the project

server_side
string
Enum: "required" "optional" "unsupported" "unknown"

The server side support of the project

body
string

A long form description of the project

status
string
Enum: "approved" "archived" "rejected" "draft" "unlisted" "processing" "withheld" "scheduled" "private" "unknown"

The status of the project

requested_status
string or null
Enum: "approved" "archived" "unlisted" "private" "draft"

The requested status when submitting for review or scheduling the project for release

additional_categories
Array of strings

A list of categories which are searchable but non-primary

issues_url
string or null

An optional link to where to submit bugs or issues with the project

source_url
string or null

An optional link to the source code of the project

wiki_url
string or null

An optional link to the project's wiki page or other relevant information

discord_url
string or null

An optional invite link to the project's discord

Array of objects (ProjectDonationURL)

A list of donation links for the project

license_id
string

The SPDX license ID of a project

license_url
string or null

The URL to this license

moderation_message
string or null

The title of the moderators' message for the project

moderation_message_body
string or null

The body of the moderators' message for the project

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Delete a project

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Get multiple projects

query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs and/or slugs of the projects

Responses

Response samples

Content type
application/json
[]

Bulk-edit multiple projects

Authorizations:
TokenAuth
query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs and/or slugs of the projects

Request Body schema: application/json

Fields to edit on all projects specified

categories
Array of strings

Set all of the categories to the categories specified here

add_categories
Array of strings

Add all of the categories specified here

remove_categories
Array of strings

Remove all of the categories specified here

additional_categories
Array of strings

Set all of the additional categories to the categories specified here

add_additional_categories
Array of strings

Add all of the additional categories specified here

remove_additional_categories
Array of strings

Remove all of the additional categories specified here

Array of objects (ProjectDonationURL)

Set all of the donation links to the donation links specified here

Array of objects (ProjectDonationURL)

Add all of the donation links specified here

Array of objects (ProjectDonationURL)

Remove all of the donation links specified here

issues_url
string or null

An optional link to where to submit bugs or issues with the projects

source_url
string or null

An optional link to the source code of the projects

wiki_url
string or null

An optional link to the projects' wiki page or other relevant information

discord_url
string or null

An optional invite link to the projects' discord

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Get a list of random projects

query Parameters
count
required
integer [ 0 .. 100 ]
Example: count=70

The number of random projects to return

Responses

Response samples

Content type
application/json
[]

Create a project

Authorizations:
TokenAuth
Request Body schema: multipart/form-data

New project

required
object (CreatableProject)
icon
string <binary>
Enum: "*.png" "*.jpg" "*.jpeg" "*.bmp" "*.gif" "*.webp" "*.svg" "*.svgz" "*.rgb"

Project icon file

Responses

Response samples

Content type
application/json
{}

Change project's icon

The new icon may be up to 256KiB in size.

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

query Parameters
ext
required
string
Enum: "png" "jpg" "jpeg" "bmp" "gif" "webp" "svg" "svgz" "rgb"

Image extension

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Delete project's icon

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Check project slug/ID validity

path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{
  • "id": "AABBCCDD"
}

Add a gallery image

Modrinth allows you to upload files of up to 5MiB to a project's gallery.

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

query Parameters
ext
required
string
Enum: "png" "jpg" "jpeg" "bmp" "gif" "webp" "svg" "svgz" "rgb"

Image extension

featured
required
boolean

Whether an image is featured

title
string

Title of the image

description
string

Description of the image

ordering
integer

Ordering of the image

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Modify a gallery image

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

query Parameters
url
required
string <uri>

URL link of the image to modify

featured
boolean

Whether the image is featured

title
string

New title of the image

description
string

New description of the image

ordering
integer

New ordering of the image

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Delete a gallery image

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

query Parameters
url
required
string <uri>

URL link of the image to delete

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Get all of a project's dependencies

path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{
  • "projects": [],
  • "versions": [
    ]
}

Follow a project

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Unfollow a project

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Schedule a project

Authorizations:
TokenAuth
path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Request Body schema: application/json

Information about date and requested status

time
required
string <ISO-8601>
requested_status
required
string
Enum: "approved" "archived" "unlisted" "private" "draft"

The requested status when scheduling the project for release

Responses

Request samples

Content type
application/json
{
  • "time": "2023-02-05T19:39:55.551839Z",
  • "requested_status": "approved"
}

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Versions

Versions contain download links to files with additional metadata.

List project's versions

path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

query Parameters
loaders
string
Example: loaders=["fabric"]

The types of loaders to filter for

game_versions
string
Example: game_versions=["1.18.1"]

The game versions to filter for

featured
boolean

Allows to filter for featured or non-featured versions only

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a version

path Parameters
id
required
string
Example: IIJJKKLL

The ID of the version

Responses

Response samples

Content type
application/json
{
  • "name": "Version 1.0.0",
  • "version_number": "1.0.0",
  • "changelog": "List of changes in this version: ...",
  • "dependencies": [
    ],
  • "game_versions": [
    ],
  • "version_type": "release",
  • "loaders": [
    ],
  • "featured": true,
  • "status": "listed",
  • "requested_status": "listed",
  • "id": "IIJJKKLL",
  • "project_id": "AABBCCDD",
  • "author_id": "EEFFGGHH",
  • "date_published": "string",
  • "downloads": 0,
  • "changelog_url": null,
  • "files": [
    ]
}

Modify a version

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: IIJJKKLL

The ID of the version

Request Body schema: application/json

Modified version fields

name
string

The name of this version

version_number
string

The version number. Ideally will follow semantic versioning

changelog
string or null

The changelog for this version

Array of objects (VersionDependency)

A list of specific versions of projects that this version depends on

game_versions
Array of strings

A list of versions of Minecraft that this version supports

version_type
string
Enum: "release" "beta" "alpha"

The release channel for this version

loaders
Array of strings

The mod loaders that this version supports

featured
boolean

Whether the version is featured or not

status
string
Enum: "listed" "archived" "draft" "unlisted" "scheduled" "unknown"
requested_status
string or null
Enum: "listed" "archived" "draft" "unlisted"
primary_file
Array of strings

The hash format and the hash of the new primary file

Array of objects (EditableFileType)

A list of file_types to edit

Responses

Request samples

Content type
application/json
{
  • "name": "Version 1.0.0",
  • "version_number": "1.0.0",
  • "changelog": "List of changes in this version: ...",
  • "dependencies": [
    ],
  • "game_versions": [
    ],
  • "version_type": "release",
  • "loaders": [
    ],
  • "featured": true,
  • "status": "listed",
  • "requested_status": "listed",
  • "primary_file": [
    ],
  • "file_types": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Delete a version

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: IIJJKKLL

The ID of the version

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Get a version given a version number or ID

Please note that, if the version number provided matches multiple versions, only the oldest matching version will be returned.

path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

id|number
required
string
Example: IIJJKKLL

The version ID or version number

Responses

Response samples

Content type
application/json
{
  • "name": "Version 1.0.0",
  • "version_number": "1.0.0",
  • "changelog": "List of changes in this version: ...",
  • "dependencies": [
    ],
  • "game_versions": [
    ],
  • "version_type": "release",
  • "loaders": [
    ],
  • "featured": true,
  • "status": "listed",
  • "requested_status": "listed",
  • "id": "IIJJKKLL",
  • "project_id": "AABBCCDD",
  • "author_id": "EEFFGGHH",
  • "date_published": "string",
  • "downloads": 0,
  • "changelog_url": null,
  • "files": [
    ]
}

Create a version

This route creates a version on an existing project. There must be at least one file attached to each new version, unless the new version's status is draft. .mrpack, .jar, .zip, and .litemod files are accepted.

The request is a multipart request with at least two form fields: one is data, which includes a JSON body with the version metadata as shown below, and at least one field containing an upload file.

You can name the file parts anything you would like, but you must list each of the parts' names in file_parts, and optionally, provide one to use as the primary file in primary_file.

Authorizations:
TokenAuth
Request Body schema: multipart/form-data

New version

required
object (CreatableVersion)
name
required
string

The name of this version

version_number
required
string

The version number. Ideally will follow semantic versioning

changelog
string or null

The changelog for this version

required
Array of objects (VersionDependency)

A list of specific versions of projects that this version depends on

game_versions
required
Array of strings

A list of versions of Minecraft that this version supports

version_type
required
string
Enum: "release" "beta" "alpha"

The release channel for this version

loaders
required
Array of strings

The mod loaders that this version supports

featured
required
boolean

Whether the version is featured or not

status
string
Enum: "listed" "archived" "draft" "unlisted" "scheduled" "unknown"
requested_status
string or null
Enum: "listed" "archived" "draft" "unlisted"
project_id
required
string

The ID of the project this version is for

file_parts
required
Array of strings

An array of the multipart field names of each file that goes with this version

primary_file
string

The multipart field name of the primary file

Responses

Response samples

Content type
application/json
{
  • "name": "Version 1.0.0",
  • "version_number": "1.0.0",
  • "changelog": "List of changes in this version: ...",
  • "dependencies": [
    ],
  • "game_versions": [
    ],
  • "version_type": "release",
  • "loaders": [
    ],
  • "featured": true,
  • "status": "listed",
  • "requested_status": "listed",
  • "id": "IIJJKKLL",
  • "project_id": "AABBCCDD",
  • "author_id": "EEFFGGHH",
  • "date_published": "string",
  • "downloads": 0,
  • "changelog_url": null,
  • "files": [
    ]
}

Schedule a version

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: IIJJKKLL

The ID of the version

Request Body schema: application/json

Information about date and requested status

time
required
string <ISO-8601>
requested_status
required
string
Enum: "approved" "archived" "unlisted" "private" "draft"

The requested status when scheduling the project for release

Responses

Request samples

Content type
application/json
{
  • "time": "2023-02-05T19:39:55.551839Z",
  • "requested_status": "approved"
}

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Get multiple versions

query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the versions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add files to version

Project files are attached. .mrpack and .jar files are accepted.

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: IIJJKKLL

The ID of the version

Request Body schema: multipart/form-data

New version files

data
object
Value: {}

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Version Files

Versions can contain multiple files, and these routes help manage those files.

Get version from hash

path Parameters
hash
required
string
Example: 619e250c133106bacc3e3b560839bd4b324dfda8

The hash of the file, considering its byte content, and encoded in hexadecimal

query Parameters
algorithm
required
string
Default: "sha1"
Enum: "sha1" "sha512"
Example: algorithm=sha512

The algorithm of the hash

multiple
boolean
Default: false

Whether to return multiple results when looking for this hash

Responses

Response samples

Content type
application/json
{
  • "name": "Version 1.0.0",
  • "version_number": "1.0.0",
  • "changelog": "List of changes in this version: ...",
  • "dependencies": [
    ],
  • "game_versions": [
    ],
  • "version_type": "release",
  • "loaders": [
    ],
  • "featured": true,
  • "status": "listed",
  • "requested_status": "listed",
  • "id": "IIJJKKLL",
  • "project_id": "AABBCCDD",
  • "author_id": "EEFFGGHH",
  • "date_published": "string",
  • "downloads": 0,
  • "changelog_url": null,
  • "files": [
    ]
}

Delete a file from its hash

Authorizations:
TokenAuth
path Parameters
hash
required
string
Example: 619e250c133106bacc3e3b560839bd4b324dfda8

The hash of the file, considering its byte content, and encoded in hexadecimal

query Parameters
algorithm
required
string
Default: "sha1"
Enum: "sha1" "sha512"
Example: algorithm=sha512

The algorithm of the hash

version_id
string
Example: version_id=IIJJKKLL

Version ID to delete the version from, if multiple files of the same hash exist

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Latest version of a project from a hash, loader(s), and game version(s)

path Parameters
hash
required
string
Example: 619e250c133106bacc3e3b560839bd4b324dfda8

The hash of the file, considering its byte content, and encoded in hexadecimal

query Parameters
algorithm
required
string
Default: "sha1"
Enum: "sha1" "sha512"
Example: algorithm=sha512

The algorithm of the hash

Request Body schema: application/json

Parameters of the updated version requested

loaders
required
Array of strings
game_versions
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "loaders": [
    ],
  • "game_versions": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "Version 1.0.0",
  • "version_number": "1.0.0",
  • "changelog": "List of changes in this version: ...",
  • "dependencies": [
    ],
  • "game_versions": [
    ],
  • "version_type": "release",
  • "loaders": [
    ],
  • "featured": true,
  • "status": "listed",
  • "requested_status": "listed",
  • "id": "IIJJKKLL",
  • "project_id": "AABBCCDD",
  • "author_id": "EEFFGGHH",
  • "date_published": "string",
  • "downloads": 0,
  • "changelog_url": null,
  • "files": [
    ]
}

Get versions from hashes

This is the same as /version_file/{hash} except it accepts multiple hashes.

Request Body schema: application/json

Hashes and algorithm of the versions requested

hashes
required
Array of strings
algorithm
required
string
Enum: "sha1" "sha512"

Responses

Request samples

Content type
application/json
{
  • "hashes": [
    ],
  • "algorithm": "sha512"
}

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Latest versions of multiple project from hashes, loader(s), and game version(s)

This is the same as /version_file/{hash}/update except it accepts multiple hashes.

Request Body schema: application/json

Parameters of the updated version requested

hashes
required
Array of strings
algorithm
required
string
Enum: "sha1" "sha512"
loaders
required
Array of strings
game_versions
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "hashes": [
    ],
  • "algorithm": "sha512",
  • "loaders": [
    ],
  • "game_versions": [
    ]
}

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Users

Users can create projects, join teams, access notifications, manage settings, and follow projects. Admins and moderators have more advanced permissions such as reviewing new projects.

Get a user

path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Responses

Response samples

Content type
application/json
{
  • "username": "my_user",
  • "name": "My User",
  • "email": "user@example.com",
  • "bio": "My short biography",
  • "payout_data": {
    },
  • "id": "EEFFGGHH",
  • "avatar_url": "https://avatars.githubusercontent.com/u/11223344?v=1",
  • "created": "string",
  • "role": "developer",
  • "badges": 63,
  • "auth_providers": [
    ],
  • "email_verified": true,
  • "has_password": true,
  • "has_totp": true,
  • "github_id": null
}

Modify a user

Authorizations:
TokenAuth
path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Request Body schema: application/json

Modified user fields

username
required
string

The user's username

name
string or null

The user's display name

email
string or null <email>

The user's email (only displayed if requesting your own account). Requires USER_READ_EMAIL PAT scope.

bio
string

A description of the user

object or null (UserPayoutData)

Various data relating to the user's payouts status (you can only see your own)

Responses

Request samples

Content type
application/json
{
  • "username": "my_user",
  • "name": "My User",
  • "email": "user@example.com",
  • "bio": "My short biography",
  • "payout_data": {
    }
}

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Get user from authorization header

Authorizations:
TokenAuth

Responses

Response samples

Content type
application/json
{
  • "username": "my_user",
  • "name": "My User",
  • "email": "user@example.com",
  • "bio": "My short biography",
  • "payout_data": {
    },
  • "id": "EEFFGGHH",
  • "avatar_url": "https://avatars.githubusercontent.com/u/11223344?v=1",
  • "created": "string",
  • "role": "developer",
  • "badges": 63,
  • "auth_providers": [
    ],
  • "email_verified": true,
  • "has_password": true,
  • "has_totp": true,
  • "github_id": null
}

Get multiple users

query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the users

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Change user's avatar

The new avatar may be up to 2MiB in size.

Authorizations:
TokenAuth
path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Get user's projects

path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Responses

Response samples

Content type
application/json
[]

Get user's followed projects

Authorizations:
TokenAuth
path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Responses

Response samples

Content type
application/json
[]

Get user's payout history

Authorizations:
TokenAuth
path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Responses

Response samples

Content type
application/json
{
  • "all_time": 10.11223344556678,
  • "last_month": 2.2244668800224465,
  • "payouts": [
    ]
}

Withdraw payout balance to PayPal or Venmo

Warning: certain amounts get withheld for fees. Please do not call this API endpoint without first acknowledging the warnings on the corresponding frontend page.

Authorizations:
TokenAuth
path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

query Parameters
amount
required
integer

Amount to withdraw

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Notifications

Notifications are sent to users for various reasons, including for project updates, team invites, and moderation purposes.

Get user's notifications

Authorizations:
TokenAuth
path Parameters
id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get notification from ID

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: NNOOPPQQ

The ID of the notification

Responses

Response samples

Content type
application/json
{
  • "id": "UUVVWWXX",
  • "user_id": "EEFFGGHH",
  • "type": "project_update",
  • "title": "**My Project** has been updated!",
  • "text": "The project, My Project, has released a new version: 1.0.0",
  • "link": "mod/AABBCCDD/version/IIJJKKLL",
  • "read": false,
  • "created": "string",
  • "actions": [
    ]
}

Mark notification as read

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: NNOOPPQQ

The ID of the notification

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Delete notification

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: NNOOPPQQ

The ID of the notification

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Get multiple notifications

Authorizations:
TokenAuth
query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the notifications

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark multiple notifications as read

Authorizations:
TokenAuth
query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the notifications

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Delete multiple notifications

Authorizations:
TokenAuth
query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the notifications

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Threads

Threads are a way of communicating between users and moderators, for the purposes of project reviews and reports.

Report a project, user, or version

Bring a project, user, or version to the attention of the moderators by reporting it.

Authorizations:
TokenAuth
Request Body schema: application/json

The report to be sent

report_type
required
string

The type of the report being sent

item_id
required
string

The ID of the item (project, version, or user) being reported

item_type
required
string
Enum: "project" "user" "version"

The type of the item being reported

body
required
string

The extended explanation of the report

Responses

Request samples

Content type
application/json
{
  • "report_type": "copyright",
  • "item_id": "EEFFGGHH",
  • "item_type": "project",
  • "body": "This is a reupload of my mod, AABBCCDD!"
}

Response samples

Content type
application/json
{
  • "report_type": "copyright",
  • "item_id": "EEFFGGHH",
  • "item_type": "project",
  • "body": "This is a reupload of my mod, AABBCCDD!",
  • "id": "VVWWXXYY",
  • "reporter": "UUVVWWXX",
  • "created": "string",
  • "closed": true,
  • "thread_id": "TTUUVVWW"
}

Get your open reports

Authorizations:
TokenAuth
query Parameters
count
integer
Example: count=100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get report from ID

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: RRSSTTUU

The ID of the report

Responses

Response samples

Content type
application/json
{
  • "report_type": "copyright",
  • "item_id": "EEFFGGHH",
  • "item_type": "project",
  • "body": "This is a reupload of my mod, AABBCCDD!",
  • "id": "VVWWXXYY",
  • "reporter": "UUVVWWXX",
  • "created": "string",
  • "closed": true,
  • "thread_id": "TTUUVVWW"
}

Modify a report

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: RRSSTTUU

The ID of the report

Request Body schema: application/json

What to modify about the report

body
string

The contents of the report

closed
boolean

Whether the thread should be closed

Responses

Request samples

Content type
application/json
{
  • "body": "This is the meat and potatoes of the report!",
  • "closed": true
}

Response samples

Content type
application/json
{
  • "error": "invalid_input",
  • "description": "Error while parsing multipart payload"
}

Get multiple reports

Authorizations:
TokenAuth
query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the reports

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a thread

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: QQRRSSTT

The ID of the thread

Responses

Response samples

Content type
application/json
{
  • "id": "WWXXYYZZ",
  • "type": "project",
  • "project_id": "string",
  • "report_id": "string",
  • "messages": [
    ],
  • "members": [
    ]
}

Send a text message to a thread

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: QQRRSSTT

The ID of the thread

Request Body schema: application/json

The message to be sent. Note that you only need the fields applicable for the text type.

type
required
string
Enum: "status_change" "text" "thread_closure" "deleted"

The type of message

body
string

The actual message text. Only present for text message type

private
boolean

Whether the message is only visible to moderators. Only present for text message type

replying_to
string or null

The ID of the message being replied to by this message. Only present for text message type

old_status
string
Enum: "approved" "archived" "rejected" "draft" "unlisted" "processing" "withheld" "scheduled" "private" "unknown"

The old status of the project. Only present for status_change message type

new_status
string
Enum: "approved" "archived" "rejected" "draft" "unlisted" "processing" "withheld" "scheduled" "private" "unknown"

The new status of the project. Only present for status_change message type

Responses

Request samples

Content type
application/json
{
  • "type": "status_change",
  • "body": "This is the text of the message.",
  • "private": false,
  • "replying_to": "SSTTUUVV",
  • "old_status": "processing",
  • "new_status": "approved"
}

Response samples

Content type
application/json
{
  • "id": "WWXXYYZZ",
  • "type": "project",
  • "project_id": "string",
  • "report_id": "string",
  • "messages": [
    ],
  • "members": [
    ]
}

Get multiple threads

Authorizations:
TokenAuth
query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the threads

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a thread message

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: IIJJKKLL

The ID of the message

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Teams

Through teams, user permissions limit how team members can modify projects.

Get a project's team members

path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a team's members

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: MMNNOOPP

The ID of the team

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a user to a team

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: MMNNOOPP

The ID of the team

Request Body schema: application/json

User to be added (must be the ID, usernames cannot be used here)

user_id
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": "EEFFGGHH"
}

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Get the members of multiple teams

query Parameters
ids
required
string
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the teams

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Join a team

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: MMNNOOPP

The ID of the team

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Modify a team member's information

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: MMNNOOPP

The ID of the team

id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Request Body schema: application/json

Contents to be modified

role
string
permissions
integer <bitfield>

The user's permissions in bitfield format

In order from first to tenth bit, the bits are:

  • UPLOAD_VERSION
  • DELETE_VERSION
  • EDIT_DETAILS
  • EDIT_BODY
  • MANAGE_INVITES
  • REMOVE_MEMBER
  • EDIT_MEMBER
  • DELETE_PROJECT
  • VIEW_ANALYTICS
  • VIEW_PAYOUTS
payouts_split
integer

The split of payouts going to this user. The proportion of payouts they get is their split divided by the sum of the splits of all members.

ordering
integer

The order of the team member.

Responses

Request samples

Content type
application/json
{
  • "role": "Contributor",
  • "permissions": 127,
  • "payouts_split": 100,
  • "ordering": 0
}

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Remove a member from a team

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: MMNNOOPP

The ID of the team

id|username
required
string
Example: EEFFGGHH,my_user

The ID or username of the user

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Transfer team's ownership to another user

Authorizations:
TokenAuth
path Parameters
id
required
string
Example: MMNNOOPP

The ID of the team

Request Body schema: application/json

New owner's ID

user_id
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": "EEFFGGHH"
}

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "description": "Authentication Error: Invalid Authentication Credentials"
}

Tags

Tags are common and reusable lists of metadata types such as categories or versions. Some can be applied to projects and/or versions.

Get a list of categories

Gets an array of categories, their icons, and applicable project types

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of loaders

Gets an array of loaders, their icons, and supported project types

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of game versions

Gets an array of game versions and information about them

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of licenses Deprecated

Deprecated - simply use SPDX IDs.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the text and title of a license

path Parameters
id
required
string
Example: LGPL-3.0-or-later

The license ID to get the text of

Responses

Response samples

Content type
application/json
{
  • "title": "GNU Lesser General Public License v3.0 or later",
  • "body": "Insert the entire text of the LGPL-3.0 here..."
}

Get a list of donation platforms

Gets an array of donation platforms and information about them

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of report types

Gets an array of valid report types

Responses

Response samples

Content type
application/json
[
  • "spam",
  • "copyright",
  • "inappropriate",
  • "malicious",
  • "name-squatting",
  • "other"
]

Get a list of project types

Gets an array of valid project types

Responses

Response samples

Content type
application/json
[
  • "mod",
  • "modpack",
  • "resourcepack",
  • "shader"
]

Get a list of side types

Gets an array of valid side types

Responses

Response samples

Content type
application/json
[
  • "required",
  • "optional",
  • "unsupported",
  • "unknown"
]

Miscellaneous

Forge Updates JSON file

If you're a Forge mod developer, your Modrinth mods have an automatically generated updates.json using the Forge Update Checker.

The only setup is to insert the URL into the [[mods]] section of your mods.toml file as such:

[[mods]]
# the other stuff here - ID, version, display name, etc. 
updateJSONURL = "https://api.modrinth.com/updates/{slug|ID}/forge_updates.json"

Replace {slug|id} with the slug or ID of your project.

Modrinth will handle the rest! When you update your mod, Forge will notify your users that their copy of your mod is out of date.

Make sure that the version format you use for your Modrinth releases is the same as the version format you use in your mods.toml. If you use a format such as 1.2.3-forge or 1.2.3+1.19 with your Modrinth releases but your mods.toml only has 1.2.3, the update checker may not function properly.

path Parameters
id|slug
required
string
Example: AABBCCDD,my_project

The ID or slug of the project

Responses

Response samples

Content type
application/json
{
  • "homepage": "https://modrinth.com",
  • "promos": {
    }
}

Various statistics about this Modrinth instance

Responses

Response samples

Content type
application/json
{
  • "projects": 0,
  • "versions": 0,
  • "files": 0,
  • "authors": 0
}

Project Model

slug
required
string

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

title
required
string

The title or name of the project

description
required
string

A short description of the project

categories
required
Array of strings

A list of the categories that the project has

client_side
required
string
Enum: "required" "optional" "unsupported" "unknown"

The client side support of the project

server_side
required
string
Enum: "required" "optional" "unsupported" "unknown"

The server side support of the project

body
required
string

A long form description of the project

status
required
string
Enum: "approved" "archived" "rejected" "draft" "unlisted" "processing" "withheld" "scheduled" "private" "unknown"

The status of the project

requested_status
string or null
Enum: "approved" "archived" "unlisted" "private" "draft"

The requested status when submitting for review or scheduling the project for release

additional_categories
Array of strings

A list of categories which are searchable but non-primary

issues_url
string or null

An optional link to where to submit bugs or issues with the project

source_url
string or null

An optional link to the source code of the project

wiki_url
string or null

An optional link to the project's wiki page or other relevant information

discord_url
string or null

An optional invite link to the project's discord

Array of objects (ProjectDonationURL)

A list of donation links for the project

project_type
required
string
Enum: "mod" "modpack" "resourcepack" "shader"

The project type of the project

downloads
required
integer

The total number of downloads of the project

icon_url
string or null

The URL of the project's icon

color
integer or null

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

thread_id
string

The ID of the moderation thread associated with this project

monetization_status
string
Enum: "monetized" "demonetized" "force-demonetized"
id
required
string

The ID of the project, encoded as a base62 string

team
required
string

The ID of the team that has ownership of this project

body_url
string or null
Deprecated
Default: null

The link to the long description of the project. Always null, only kept for legacy compatibility.

object or null (ModeratorMessage)
Deprecated

A message that a moderator sent regarding the project

published
required
string <ISO-8601>

The date the project was published

updated
required
string <ISO-8601>

The date the project was last updated

approved
string or null <ISO-8601>

The date the project's status was set to an approved status

queued
string or null <ISO-8601>

The date the project's status was submitted to moderators for review

followers
required
integer

The total number of users following the project