Skip to main content
API docs by Redocly

Labrinth (v2.7.0/3b22f59)

Download OpenAPI specification:Download

Remember to join our Discord if you need any support!

Authentication

This API uses GitHub tokens for authentication. The token is in the Authorization header of the request.

Example:

Authorization: gho_pJ9dGXVKpfzZp4PUHSxYEq9hjk0h288Gwj4S

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 and notifications)

Applications interacting with the authenticated API should either retrieve the Modrinth GitHub token through the site or create a personal app token for use with Modrinth. The API provides a couple routes for auth -- don't implement this flow in your application! Instead, use a personal access token or create your own GitHub OAuth2 application. This system will be revisited and allow easier interaction with the authenticated subset of the API once we roll out our own authentication system.

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.

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)

Projects

Projects can be mods or modpacks and are created by users.

Search projects

query Parameters
query
string
Example: query=gravestones

The query to search for

facets
Array of strings[ items ]
Example: facets=[["categories:forge"],["versions:1.17.1"],["project_type:mod"],["license:mit"]]

The recommended way of filtering search results. Learn more about using facets.

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
Default: 10
Example: limit=20

The number of results returned by the search

filters
string
Example: filters=categories="fabric" AND (categories="technology" OR categories="utility")

A list of filters relating to the properties of a project. Use filters when there isn't an available facet for your needs. More information

version
string
Deprecated
Example: version=version="1.16.3" OR version="1.16.2" OR version="1.16.1"

A list of filters relating to the versions of a project. Use of facets for filtering by version is recommended

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"

The client side support of the project

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

The server side support of the project

body
string

A long form description of the project

additional_categories
Array of arrays

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

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

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

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
Array of strings
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the projects

Responses

Response samples

Content type
application/json
[]

Edit multiple projects

query Parameters
ids
required
Array of strings
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs 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

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

Array of objects

Add all of the donation links specified here

Array of objects

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

^gallery-[0-9]+$
pattern property
string <binary>
Deprecated
Enum: "*.png" "*.jpg" "*.jpeg" "*.bmp" "*.gif" "*.webp" "*.svg" "*.svgz" "*.rgb"

A project gallery image file. Deprecated - please upload gallery images after initial upload.

^version-[0-9]+-[0-9]+$
pattern property
string
Deprecated

A version file. Deprecated - please upload version files after initial upload.

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: image/*
string <binary> <image/png, image/jpeg, image/bmp, image/gif, image/webp, image/svg, image/svgz, image/rgb>

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: image/*

New gallery image

string <binary> <image/png, image/jpeg, image/bmp, image/gif, image/webp, image/svg, image/svgz, image/rgb>

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
Array of strings
Example: loaders=["fabric"]

The types of loaders to filter for

game_versions
Array of strings
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

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

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"
}

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

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: "listed" "archived" "draft" "unlisted"

The requested status when scheduling the version for release

Responses

Request samples

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

Response samples

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

Get multiple versions

query Parameters
ids
required
Array of strings
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
{
  • "your_hash_here": {
    }
}

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
{
  • "your_hash_here": {
    }
}

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",
  • "github_id": 11223344,
  • "avatar_url": "https://avatars.githubusercontent.com/u/11223344?v=1",
  • "created": "string",
  • "role": "developer",
  • "badges": 63
}

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 your own is ever displayed)

bio
string

A description of the user

object or null

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"
}

Delete a user

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
{
  • "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",
  • "github_id": 11223344,
  • "avatar_url": "https://avatars.githubusercontent.com/u/11223344?v=1",
  • "created": "string",
  • "role": "developer",
  • "badges": 63
}

Get multiple users

query Parameters
ids
required
Array of strings
Example: ids=["AABBCCDD", "EEFFGGHH"]

The IDs of the users

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Change user's avatar

By default, Modrinth uses a user's GitHub icon. This route allows it to be changed to a custom one. 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: image/*
string <binary> <image/png, image/jpeg, image/bmp, image/gif, image/webp, image/svg, image/svgz, image/rgb>

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 notifications

Notifications can be project updates or team invites

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 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"
}

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
Array of strings
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

user_id
required
string

The ID of the user to modify

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

Gets an array of licenses and information about them

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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"
]

Miscellaneous

Report a project, user, or version

Bring a project, user, or version to the attention of the moderators by reporting it. You must be logged in to report anything.

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!",
  • "reporter": "UUVVWWXX",
  • "created": "string"
}

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"

The client side support of the project

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

The server side support of the project

body
required
string

A long form description of the project

additional_categories
Array of arrays

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

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

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

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 approved or unlisted

followers
required
integer

The total number of users following the project

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

The status of the project

object

The license of the project

versions
Array of strings

A list of the version IDs of the project (will never be empty unless draft status)

game_versions
Array of strings

A list of all of the game versions supported by the project

loaders
Array of strings

A list of all of the loaders supported by the project

Array of objects or null

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

{}

Search Result 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
Array of strings

A list of the categories that the project has

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

The client side support of the project

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

The server side support of 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

project_id
required
string

The ID of the project

author
required
string

The username of the project's author

display_categories
Array of strings

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

versions
required
Array of strings

A list of the minecraft versions supported by the project

follows
required
integer

The total number of users following the project

date_created
required
string <ISO-8601>

The date the project was added to search

date_modified
required
string <ISO-8601>

The date the project was last modified

latest_version
string

The latest version of minecraft that this project supports

license
required
string

The SPDX license ID of a project

gallery
Array of strings

All gallery images attached to the project

featured_gallery
string or null

The featured gallery image of the project

{}

Version Model

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

Array of objects

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"
id
required
string

The ID of the version, encoded as a base62 string

project_id
required
string

The ID of the project this version is for

author_id
required
string

The ID of the author who published this version

date_published
required
string <ISO-8601>
downloads
required
integer

The number of times this version has been downloaded

changelog_url
string or null
Deprecated

A link to the changelog for this version. Always null, only kept for legacy compatibility.

required
Array of objects

A list of files available for download for this version

{
  • "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": [
    ]
}

User Model

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 your own is ever displayed)

bio
string

A description of the user

object or null

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

id
required
string

The user's id

github_id
integer or null

The user's github id

avatar_url
required
string

The user's avatar url

created
required
string <ISO-8601>

The time at which the user was created

role
required
string
Enum: "admin" "moderator" "developer"

The user's role

badges
integer <bitfield>

Any badges applicable to this user. These are currently unused and undisplayed, and as such are subject to change

In order from first to seventh bit, the current bits are:

  • (unused)
  • EARLY_MODPACK_ADOPTER
  • EARLY_RESPACK_ADOPTER
  • EARLY_PLUGIN_ADOPTER
  • ALPHA_TESTER
  • CONTRIBUTOR
  • TRANSLATOR
{
  • "username": "my_user",
  • "name": "My User",
  • "email": "user@example.com",
  • "bio": "My short biography",
  • "payout_data": {
    },
  • "id": "EEFFGGHH",
  • "github_id": 11223344,
  • "avatar_url": "https://avatars.githubusercontent.com/u/11223344?v=1",
  • "created": "string",
  • "role": "developer",
  • "badges": 63
}

Team Member Model

team_id
required
string

The ID of the team this team member is a member of

required
object (User)
role
required
string

The user's role on the team

permissions
integer <bitfield>

The user's permissions in bitfield format (requires authorization to view)

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
accepted
required
boolean

Whether or not the user has accepted to be on the team (requires authorization to view)

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.

{
  • "team_id": "MMNNOOPP",
  • "user": {
    },
  • "role": "Member",
  • "permissions": 127,
  • "accepted": true,
  • "payouts_split": 100,
  • "ordering": 0
}