Labrinth (v2.7.0/15cf3fc)
Download OpenAPI specification:Download
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
.
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.
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.
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.
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 minuteX-Ratelimit-Remaining
: the number of requests remaining in the current ratelimit windowX-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.
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)
orUser-Agent: github_username/project_name/1.56.0 (contact@launcher.com)
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 bemod
ormodpack
),moderation_message
(which has amessage
andbody
),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 asproject_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.
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:
Several others are also available for use, though these should not be used outside very specific use cases.
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
Examples:
You then join these strings together in arrays to signal ORAll elements in a single array are considered to be joined by OR statements. ANDSeparate arrays are considered to be joined by AND statements. |
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
- 200
- 400
{- "hits": [
- {
- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "project_id": "AABBCCDD",
- "author": "my_user",
- "display_categories": [
- "technology",
- "fabric"
], - "versions": [
- "1.8",
- "1.8.9"
], - "follows": 0,
- "date_created": "string",
- "date_modified": "string",
- "latest_version": "1.8.9",
- "license": "MIT",
- "featured_gallery": "string"
}
], - "offset": 0,
- "limit": 10,
- "total_hits": 10
}
Get a project
path Parameters
id|slug required | string Example: AABBCCDD,my_project The ID or slug of the project |
Responses
Response samples
- 200
{- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "id": "AABBCCDD",
- "team": "MMNNOOPP",
- "body_url": null,
- "moderator_message": null,
- "published": "string",
- "updated": "string",
- "approved": "string",
- "queued": "string",
- "followers": 0,
- "license": {
- "id": "LGPL-3.0-or-later",
- "name": "GNU Lesser General Public License v3 or later",
- "url": "string"
}, - "versions": [
- "IIJJKKLL",
- "QQRRSSTT"
], - "game_versions": [
- "1.19",
- "1.19.1",
- "1.19.2",
- "1.19.3"
], - "loaders": [
- "forge",
- "fabric",
- "quilt"
], - "gallery": [
- {
- "featured": true,
- "title": "My awesome screenshot!",
- "description": "This awesome screenshot shows all of the blocks in my mod!",
- "created": "string",
- "ordering": 0
}
]
}
Modify a project
Authorizations:
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: |
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
- Payload
{- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "license_id": "LGPL-3.0-or-later",
- "license_url": "string",
- "moderation_message": "string",
- "moderation_message_body": "string"
}
Response samples
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
Get multiple projects
query Parameters
ids required | string Example: ids=["AABBCCDD", "EEFFGGHH"] The IDs and/or slugs of the projects |
Responses
Response samples
- 200
[- {
- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "id": "AABBCCDD",
- "team": "MMNNOOPP",
- "body_url": null,
- "moderator_message": null,
- "published": "string",
- "updated": "string",
- "approved": "string",
- "queued": "string",
- "followers": 0,
- "license": {
- "id": "LGPL-3.0-or-later",
- "name": "GNU Lesser General Public License v3 or later",
- "url": "string"
}, - "versions": [
- "IIJJKKLL",
- "QQRRSSTT"
], - "game_versions": [
- "1.19",
- "1.19.1",
- "1.19.2",
- "1.19.3"
], - "loaders": [
- "forge",
- "fabric",
- "quilt"
], - "gallery": [
- {
- "featured": true,
- "title": "My awesome screenshot!",
- "description": "This awesome screenshot shows all of the blocks in my mod!",
- "created": "string",
- "ordering": 0
}
]
}
]
Bulk-edit multiple projects
Authorizations:
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
- Payload
{- "categories": [
- "string"
], - "add_categories": [
- "string"
], - "remove_categories": [
- "string"
], - "additional_categories": [
- "string"
], - "add_additional_categories": [
- "string"
], - "remove_additional_categories": [
- "string"
], - "donation_urls": [
], - "add_donation_urls": [
], - "remove_donation_urls": [
],
}
Response samples
- 400
- 401
{- "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
- 200
- 400
[- {
- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "id": "AABBCCDD",
- "team": "MMNNOOPP",
- "body_url": null,
- "moderator_message": null,
- "published": "string",
- "updated": "string",
- "approved": "string",
- "queued": "string",
- "followers": 0,
- "license": {
- "id": "LGPL-3.0-or-later",
- "name": "GNU Lesser General Public License v3 or later",
- "url": "string"
}, - "versions": [
- "IIJJKKLL",
- "QQRRSSTT"
], - "game_versions": [
- "1.19",
- "1.19.1",
- "1.19.2",
- "1.19.3"
], - "loaders": [
- "forge",
- "fabric",
- "quilt"
], - "gallery": [
- {
- "featured": true,
- "title": "My awesome screenshot!",
- "description": "This awesome screenshot shows all of the blocks in my mod!",
- "created": "string",
- "ordering": 0
}
]
}
]
Create a project
Authorizations:
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
- 200
- 400
- 401
{- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "id": "AABBCCDD",
- "team": "MMNNOOPP",
- "body_url": null,
- "moderator_message": null,
- "published": "string",
- "updated": "string",
- "approved": "string",
- "queued": "string",
- "followers": 0,
- "license": {
- "id": "LGPL-3.0-or-later",
- "name": "GNU Lesser General Public License v3 or later",
- "url": "string"
}, - "versions": [
- "IIJJKKLL",
- "QQRRSSTT"
], - "game_versions": [
- "1.19",
- "1.19.1",
- "1.19.2",
- "1.19.3"
], - "loaders": [
- "forge",
- "fabric",
- "quilt"
], - "gallery": [
- {
- "featured": true,
- "title": "My awesome screenshot!",
- "description": "This awesome screenshot shows all of the blocks in my mod!",
- "created": "string",
- "ordering": 0
}
]
}
Change project's icon
The new icon may be up to 256KiB in size.
Authorizations:
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:
Responses
Response samples
- 400
{- "error": "invalid_input",
- "description": "Error while parsing multipart payload"
}
Add a gallery image
Modrinth allows you to upload files of up to 5MiB to a project's gallery.
Authorizations:
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:
Responses
Response samples
- 400
- 401
{- "error": "invalid_input",
- "description": "Error while parsing multipart payload"
}
Modify a gallery image
Authorizations:
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
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
Delete a gallery image
Authorizations:
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
- 400
- 401
{- "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
- 200
{- "projects": [
- {
- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "id": "AABBCCDD",
- "team": "MMNNOOPP",
- "body_url": null,
- "moderator_message": null,
- "published": "string",
- "updated": "string",
- "approved": "string",
- "queued": "string",
- "followers": 0,
- "license": {
- "id": "LGPL-3.0-or-later",
- "name": "GNU Lesser General Public License v3 or later",
- "url": "string"
}, - "versions": [
- "IIJJKKLL",
- "QQRRSSTT"
], - "game_versions": [
- "1.19",
- "1.19.1",
- "1.19.2",
- "1.19.3"
], - "loaders": [
- "forge",
- "fabric",
- "quilt"
], - "gallery": [
- {
- "featured": true,
- "title": "My awesome screenshot!",
- "description": "This awesome screenshot shows all of the blocks in my mod!",
- "created": "string",
- "ordering": 0
}
]
}
], - "versions": [
- {
- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
]
}
Schedule a project
Authorizations:
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
- Payload
{- "time": "2023-02-05T19:39:55.551839Z",
- "requested_status": "approved"
}
Response samples
- 400
- 401
{- "error": "invalid_input",
- "description": "Error while parsing multipart payload"
}
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
- 200
[- {
- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
]
Response samples
- 200
{- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
Modify a version
Authorizations:
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
- Payload
{- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "primary_file": [
- "sha1",
- "aaaabbbbccccddddeeeeffffgggghhhhiiiijjjj"
], - "file_types": [
- {
- "algorithm": "sha1",
- "hash": "aaaabbbbccccddddeeeeffffgggghhhhiiiijjjj",
- "file_type": "required-resource-pack"
}
]
}
Response samples
- 401
{- "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
- 200
{- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
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:
Request Body schema: multipart/form-data
New version
required | object (CreatableVersion) | ||||||||||||||||||||||||||
|
Responses
Response samples
- 200
- 400
- 401
{- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
Schedule a version
Authorizations:
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
- Payload
{- "time": "2023-02-05T19:39:55.551839Z",
- "requested_status": "approved"
}
Response samples
- 400
- 401
{- "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
- 200
[- {
- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
]
Add files to version
Project files are attached. .mrpack
and .jar
files are accepted.
Authorizations:
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
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
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
- 200
{- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
Delete a file from its hash
Authorizations:
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
- 401
{- "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
- Payload
{- "loaders": [
- [
- "fabric"
]
], - "game_versions": [
- "1.18",
- "1.18.1"
]
}
Response samples
- 200
{- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
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
- Payload
{- "hashes": [
- "ea0f38408102e4d2efd53c2cc11b88b711996b48d8922f76ea6abf731219c5bd1efe39ddf9cce77c54d49a62ff10fb685c00d2e4c524ab99d20f6296677ab2c4",
- "925a5c4899affa4098d997dfa4a4cb52c636d539e94bc489d1fa034218cb96819a70eb8b01647a39316a59fcfe223c1a8c05ed2e2ae5f4c1e75fa48f6af1c960"
], - "algorithm": "sha512"
}
Response samples
- 200
{- "property1": {
- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}, - "property2": {
- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
}
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
- Payload
{- "hashes": [
- "ea0f38408102e4d2efd53c2cc11b88b711996b48d8922f76ea6abf731219c5bd1efe39ddf9cce77c54d49a62ff10fb685c00d2e4c524ab99d20f6296677ab2c4",
- "925a5c4899affa4098d997dfa4a4cb52c636d539e94bc489d1fa034218cb96819a70eb8b01647a39316a59fcfe223c1a8c05ed2e2ae5f4c1e75fa48f6af1c960"
], - "algorithm": "sha512",
- "loaders": [
- "fabric"
], - "game_versions": [
- "1.18",
- "1.18.1"
]
}
Response samples
- 200
{- "property1": {
- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}, - "property2": {
- "name": "Version 1.0.0",
- "version_number": "1.0.0",
- "changelog": "List of changes in this version: ...",
- "dependencies": [
- {
- "version_id": "IIJJKKLL",
- "project_id": "QQRRSSTT",
- "file_name": "sodium-fabric-mc1.19-0.4.2+build.16.jar",
- "dependency_type": "required"
}
], - "game_versions": [
- "1.16.5",
- "1.17.1"
], - "version_type": "release",
- "loaders": [
- "fabric",
- "forge"
], - "featured": true,
- "status": "listed",
- "requested_status": "listed",
- "id": "IIJJKKLL",
- "project_id": "AABBCCDD",
- "author_id": "EEFFGGHH",
- "date_published": "string",
- "downloads": 0,
- "changelog_url": null,
- "files": [
- {
- "hashes": {
- "sha512": "93ecf5fe02914fb53d94aa3d28c1fb562e23985f8e4d48b9038422798618761fe208a31ca9b723667a4e05de0d91a3f86bcd8d018f6a686c39550e21b198d96f",
- "sha1": "c84dd4b3580c02b79958a0590afd5783d80ef504"
}, - "filename": "my_file.jar",
- "primary": false,
- "size": 1097270,
- "file_type": "required-resource-pack"
}
]
}
}
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
- 200
{- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}
Modify a user
Authorizations:
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 |
string or null <email> The user's email (only displayed if requesting your own account). Requires | |
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
- Payload
{- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}
}
Response samples
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
Response samples
- 200
- 401
{- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "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
- 200
[- {
- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}
]
Change user's avatar
The new avatar may be up to 2MiB in size.
Authorizations:
path Parameters
id|username required | string Example: EEFFGGHH,my_user The ID or username of the user |
Request Body schema:
Responses
Response samples
- 400
{- "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
- 200
[- {
- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "id": "AABBCCDD",
- "team": "MMNNOOPP",
- "body_url": null,
- "moderator_message": null,
- "published": "string",
- "updated": "string",
- "approved": "string",
- "queued": "string",
- "followers": 0,
- "license": {
- "id": "LGPL-3.0-or-later",
- "name": "GNU Lesser General Public License v3 or later",
- "url": "string"
}, - "versions": [
- "IIJJKKLL",
- "QQRRSSTT"
], - "game_versions": [
- "1.19",
- "1.19.1",
- "1.19.2",
- "1.19.3"
], - "loaders": [
- "forge",
- "fabric",
- "quilt"
], - "gallery": [
- {
- "featured": true,
- "title": "My awesome screenshot!",
- "description": "This awesome screenshot shows all of the blocks in my mod!",
- "created": "string",
- "ordering": 0
}
]
}
]
Get user's followed projects
Authorizations:
path Parameters
id|username required | string Example: EEFFGGHH,my_user The ID or username of the user |
Responses
Response samples
- 200
- 401
[- {
- "slug": "my_project",
- "title": "My Project",
- "description": "A short description",
- "categories": [
- "technology",
- "adventure",
- "fabric"
], - "client_side": "required",
- "server_side": "optional",
- "body": "A long body describing my project in detail",
- "status": "approved",
- "requested_status": "approved",
- "additional_categories": [
- "technology",
- "adventure",
- "fabric"
], - "donation_urls": [
], - "project_type": "mod",
- "downloads": 0,
- "color": 8703084,
- "thread_id": "TTUUVVWW",
- "monetization_status": "monetized",
- "id": "AABBCCDD",
- "team": "MMNNOOPP",
- "body_url": null,
- "moderator_message": null,
- "published": "string",
- "updated": "string",
- "approved": "string",
- "queued": "string",
- "followers": 0,
- "license": {
- "id": "LGPL-3.0-or-later",
- "name": "GNU Lesser General Public License v3 or later",
- "url": "string"
}, - "versions": [
- "IIJJKKLL",
- "QQRRSSTT"
], - "game_versions": [
- "1.19",
- "1.19.1",
- "1.19.2",
- "1.19.3"
], - "loaders": [
- "forge",
- "fabric",
- "quilt"
], - "gallery": [
- {
- "featured": true,
- "title": "My awesome screenshot!",
- "description": "This awesome screenshot shows all of the blocks in my mod!",
- "created": "string",
- "ordering": 0
}
]
}
]
Get user's payout history
Authorizations:
path Parameters
id|username required | string Example: EEFFGGHH,my_user The ID or username of the user |
Responses
Response samples
- 200
- 401
{- "all_time": 10.11223344556678,
- "last_month": 2.2244668800224465,
- "payouts": [
- {
- "created": "string",
- "amount": 10,
- "status": "success"
}
]
}
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:
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
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
Notifications are sent to users for various reasons, including for project updates, team invites, and moderation purposes.
Get user's notifications
Authorizations:
path Parameters
id|username required | string Example: EEFFGGHH,my_user The ID or username of the user |
Responses
Response samples
- 200
- 401
[- {
- "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": [
- {
- "title": "Accept",
- "action_route": [
- "POST",
- "team/{id}/join"
]
}
]
}
]
Get notification from ID
Authorizations:
path Parameters
id required | string Example: NNOOPPQQ The ID of the notification |
Responses
Response samples
- 200
- 401
{- "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": [
- {
- "title": "Accept",
- "action_route": [
- "POST",
- "team/{id}/join"
]
}
]
}
Get multiple notifications
Authorizations:
query Parameters
ids required | string Example: ids=["AABBCCDD", "EEFFGGHH"] The IDs of the notifications |
Responses
Response samples
- 200
- 401
[- {
- "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": [
- {
- "title": "Accept",
- "action_route": [
- "POST",
- "team/{id}/join"
]
}
]
}
]
Mark multiple notifications as read
Authorizations:
query Parameters
ids required | string Example: ids=["AABBCCDD", "EEFFGGHH"] The IDs of the notifications |
Responses
Response samples
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
Delete multiple notifications
Authorizations:
query Parameters
ids required | string Example: ids=["AABBCCDD", "EEFFGGHH"] The IDs of the notifications |
Responses
Response samples
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
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:
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
- Payload
{- "report_type": "copyright",
- "item_id": "EEFFGGHH",
- "item_type": "project",
- "body": "This is a reupload of my mod, AABBCCDD!"
}
Response samples
- 200
- 400
- 401
{- "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:
query Parameters
count | integer Example: count=100 |
Responses
Response samples
- 200
- 401
[- {
- "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 report from ID
Authorizations:
path Parameters
id required | string Example: RRSSTTUU The ID of the report |
Responses
Response samples
- 200
- 401
{- "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:
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
- Payload
{- "body": "This is the meat and potatoes of the report!",
- "closed": true
}
Response samples
- 400
- 401
{- "error": "invalid_input",
- "description": "Error while parsing multipart payload"
}
Get multiple reports
Authorizations:
query Parameters
ids required | string Example: ids=["AABBCCDD", "EEFFGGHH"] The IDs of the reports |
Responses
Response samples
- 200
- 401
[- {
- "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 a thread
Authorizations:
path Parameters
id required | string Example: QQRRSSTT The ID of the thread |
Responses
Response samples
- 200
{- "id": "WWXXYYZZ",
- "type": "project",
- "project_id": "string",
- "report_id": "string",
- "messages": [
- {
- "id": "MMNNOOPP",
- "author_id": "QQRRSSTT",
- "body": {
- "type": "status_change",
- "body": "This is the text of the message.",
- "private": false,
- "replying_to": "SSTTUUVV",
- "old_status": "processing",
- "new_status": "approved"
}, - "created": "string"
}
], - "members": [
- {
- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}
]
}
Send a text message to a thread
Authorizations:
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 |
private | boolean Whether the message is only visible to moderators. Only present for |
replying_to | string or null The ID of the message being replied to by this message. Only present for |
old_status | string Enum: "approved" "archived" "rejected" "draft" "unlisted" "processing" "withheld" "scheduled" "private" "unknown" The old status of the project. Only present for |
new_status | string Enum: "approved" "archived" "rejected" "draft" "unlisted" "processing" "withheld" "scheduled" "private" "unknown" The new status of the project. Only present for |
Responses
Request samples
- Payload
{- "type": "status_change",
- "body": "This is the text of the message.",
- "private": false,
- "replying_to": "SSTTUUVV",
- "old_status": "processing",
- "new_status": "approved"
}
Response samples
- 200
- 400
{- "id": "WWXXYYZZ",
- "type": "project",
- "project_id": "string",
- "report_id": "string",
- "messages": [
- {
- "id": "MMNNOOPP",
- "author_id": "QQRRSSTT",
- "body": {
- "type": "status_change",
- "body": "This is the text of the message.",
- "private": false,
- "replying_to": "SSTTUUVV",
- "old_status": "processing",
- "new_status": "approved"
}, - "created": "string"
}
], - "members": [
- {
- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}
]
}
Get multiple threads
Authorizations:
query Parameters
ids required | string Example: ids=["AABBCCDD", "EEFFGGHH"] The IDs of the threads |
Responses
Response samples
- 200
[- {
- "id": "WWXXYYZZ",
- "type": "project",
- "project_id": "string",
- "report_id": "string",
- "messages": [
- {
- "id": "MMNNOOPP",
- "author_id": "QQRRSSTT",
- "body": {
- "type": "status_change",
- "body": "This is the text of the message.",
- "private": false,
- "replying_to": "SSTTUUVV",
- "old_status": "processing",
- "new_status": "approved"
}, - "created": "string"
}
], - "members": [
- {
- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}
]
}
]
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
- 200
[- {
- "team_id": "MMNNOOPP",
- "user": {
- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}, - "role": "Member",
- "permissions": 127,
- "accepted": true,
- "payouts_split": 100,
- "ordering": 0
}
]
Get a team's members
Authorizations:
path Parameters
id required | string Example: MMNNOOPP The ID of the team |
Responses
Response samples
- 200
[- {
- "team_id": "MMNNOOPP",
- "user": {
- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}, - "role": "Member",
- "permissions": 127,
- "accepted": true,
- "payouts_split": 100,
- "ordering": 0
}
]
Add a user to a team
Authorizations:
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
- Payload
{- "user_id": "EEFFGGHH"
}
Response samples
- 401
{- "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
- 200
[- [
- {
- "team_id": "MMNNOOPP",
- "user": {
- "username": "my_user",
- "name": "My User",
- "email": "user@example.com",
- "bio": "My short biography",
- "payout_data": {
- "balance": 10.11223344556678,
- "payout_wallet": "paypal",
- "payout_wallet_type": "email",
- "payout_address": "support@modrinth.com"
}, - "id": "EEFFGGHH",
- "created": "string",
- "role": "developer",
- "badges": 63,
- "auth_providers": [
- "github",
- "gitlab",
- "steam",
- "microsoft",
- "google",
- "discord"
], - "email_verified": true,
- "has_password": true,
- "has_totp": true,
- "github_id": null
}, - "role": "Member",
- "permissions": 127,
- "accepted": true,
- "payouts_split": 100,
- "ordering": 0
}
]
]
Modify a team member's information
Authorizations:
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:
|
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
- Payload
{- "role": "Contributor",
- "permissions": 127,
- "payouts_split": 100,
- "ordering": 0
}
Response samples
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
Remove a member from a team
Authorizations:
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
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
Transfer team's ownership to another user
Authorizations:
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
- Payload
{- "user_id": "EEFFGGHH"
}
Response samples
- 401
{- "error": "unauthorized",
- "description": "Authentication Error: Invalid Authentication Credentials"
}
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
- 200
- 400
{- "promos": {
- "{version}-recommended": "string",
- "{version}-latest": "string"
}
}
slug required | string The slug of a project, used for vanity URLs. Regex: |
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 |