Versions API

Get Version

Retrieve a single version by its ID.

GET /v3/version/{id}

Path Parameters

string

required

The version ID

Response

string

The version’s unique ID

project_id

string

The ID of the project this version belongs to

name

string

The version’s name/title

version_number

string

The version number (e.g., “1.0.0”)

changelog

string

The version’s changelog (Markdown)

version_type

string

Version type: release, beta, or alpha

status

string

Version status: listed, archived, draft, unlisted, scheduled, unknown

featured

boolean

Whether this version is featured

loaders

array

List of compatible mod loaders (e.g., [“fabric”, “quilt”])

dependencies

array

List of version dependencies

Show properties

project_id

string

The ID of the dependency project

version_id

string

Specific version ID (if applicable)

file_name

string

Specific file name (if applicable)

dependency_type

string

Type: required, optional, incompatible, or embedded

files

array

List of files in this version

Show properties

hashes

object

File hashes (sha1, sha512)

url

string

Download URL

filename

string

File name

primary

boolean

Whether this is the primary file

size

integer

File size in bytes

file_type

string

File type: required-resource-pack or optional-resource-pack

date_published

string

ISO 8601 timestamp of publication

downloads

integer

Download count

Example Request

curl https://api.modrinth.com/v3/version/AANobbMI

Example Response

{
  "id": "AANobbMI",
  "project_id": "AANobbMI",
  "name": "Sodium 0.5.8",
  "version_number": "mc1.20.4-0.5.8",
  "changelog": "## Changes\n- Fixed rendering issues...",
  "version_type": "release",
  "status": "listed",
  "featured": true,
  "loaders": ["fabric", "quilt"],
  "dependencies": [
    {
      "project_id": "P7dR8mSH",
      "dependency_type": "required"
    }
  ],
  "files": [
    {
      "hashes": {
        "sha1": "abc123...",
        "sha512": "def456..."
      },
      "url": "https://cdn.modrinth.com/data/AANobbMI/versions/...",
      "filename": "sodium-fabric-0.5.8.jar",
      "primary": true,
      "size": 524288
    }
  ],
  "date_published": "2024-01-15T10:30:00Z",
  "downloads": 150000
}

Get Multiple Versions

Retrieve multiple versions by their IDs.

GET /v3/versions?ids=["id1","id2"]&include_changelog=true

Query Parameters

ids

string

required

JSON array of version IDs as a string

include_changelog

boolean

Whether to include changelog text (default: true)

Example Request

curl 'https://api.modrinth.com/v3/versions?ids=["AANobbMI","BBxxyyzz"]&include_changelog=false'

Get Project Versions

Get all versions for a project with optional filtering.

GET /v3/project/{project_id}/version

Path Parameters

project_id

string

required

The project ID or slug

Query Parameters

loaders

string

JSON array of loaders to filter by (e.g., ["fabric","quilt"])

featured

boolean

Filter to only featured versions

version_type

string

Filter by version type: release, beta, or alpha

limit

integer

Maximum number of versions to return

offset

integer

Offset for pagination

loader_fields

string

JSON object of loader fields to filter by (e.g., {"game_versions":["1.20.4"]})

include_changelog

boolean

Whether to include changelog (default: true)

Example Request

curl 'https://api.modrinth.com/v3/project/sodium/version?loaders=["fabric"]&limit=10'

Get Version by Number

Get a specific version by project and version number.

GET /v3/project/{project_id}/version/{version_number}

Path Parameters

project_id

string

required

The project ID or slug

version_number

string

required

The version number or version ID

Example Request

curl https://api.modrinth.com/v3/project/sodium/version/mc1.20.4-0.5.8

Create Version

Create a new version for a project. Requires authentication and VERSION_CREATE scope.

POST /v3/version

Request Body (multipart/form-data)

data

JSON

required

Version metadata as JSON:

Show properties

project_id

string

required

The project ID

version_number

string

required

Version number (1-32 characters, URL-safe)

version_title

string

required

Version title/name (1-64 characters)

version_body

string

Changelog in Markdown (max 65536 characters)

release_channel

string

required

Version type: release, beta, or alpha

loaders

array

required

List of compatible loaders (e.g., [“fabric”, “forge”])

featured

boolean

Whether to feature this version

dependencies

array

List of dependencies (max 4096)

file_parts

array

required

List of file part names from the multipart request

primary_file

string

Name of the primary file

status

string

Version status (default: listed)

file_types

object

Map of filenames to file types

ordering

integer

Custom ordering value

file

required

One or more file parts (referenced in file_parts)

Example Request

curl -X POST https://api.modrinth.com/v3/version \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'data={
    "project_id": "AANobbMI",
    "version_number": "1.0.0",
    "version_title": "Release 1.0.0",
    "version_body": "Initial release",
    "release_channel": "release",
    "loaders": ["fabric"],
    "featured": true,
    "dependencies": [],
    "file_parts": ["file"],
    "game_versions": ["1.20.4"]
  }' \
  -F '[email protected]'

Update Version

Update version metadata. Requires authentication and VERSION_WRITE scope.

PATCH /v3/version/{id}

Path Parameters

string

required

The version ID

Request Body

name

string

New version name (1-64 characters)

version_number

string

New version number (1-32 characters)

changelog

string

New changelog (max 65536 characters)

version_type

string

New version type: release, beta, or alpha

dependencies

array

New dependencies list (max 4096)

loaders

array

New loaders list

featured

boolean

Set featured status

status

string

New status

file_types

array

Update file types for existing files

ordering

integer

Custom ordering value

Example Request

curl -X PATCH https://api.modrinth.com/v3/version/AANobbMI \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sodium 0.5.9",
    "changelog": "## Bug Fixes\n- Fixed memory leak",
    "featured": true
  }'

Delete Version

Delete a version. Requires authentication and VERSION_DELETE scope.

DELETE /v3/version/{id}

Path Parameters

string

required

The version ID

Example Request

curl -X DELETE https://api.modrinth.com/v3/version/AANobbMI \
  -H "Authorization: Bearer YOUR_TOKEN"

Upload File to Version

Add additional files to an existing version. Requires authentication.

POST /v3/version/{version_id}/file

Path Parameters

version_id

string

required

The version ID

Request Body (multipart/form-data)

data

JSON

Optional file metadata

file

required

The file to upload

Common Use Cases

Publishing a New Version

Prepare version metadata (name, version number, changelog)
Build and test your mod/modpack files
Create version via POST /v3/version with multipart form data
Wait for automatic validation and processing

Managing Dependencies

Use project_id for general dependency on any version
Use version_id for specific version requirement
Use file_name for external dependencies
Types: required (must have), optional (recommended), incompatible (conflicts), embedded (bundled)

Loader Fields Loader-specific fields can be passed as flattened properties:

game_versions: Array of Minecraft versions (e.g., [“1.20.4”, “1.20.3”])
Other loader-specific fields depend on the loader type

File Types

Primary file: Main mod/modpack JAR
required-resource-pack: Must be installed with the mod
optional-resource-pack: Optional companion resource pack

Version Ordering

Versions are typically ordered by date_published (newest first)
Use ordering field for custom sort order
Use featured flag to highlight important versions

Getting Started

Core Resources

Content & Search

Server Hosting API

Client Libraries

Get Version

Path Parameters

Response

Example Request

Example Response

Get Multiple Versions

Query Parameters

Example Request

Get Project Versions

Path Parameters

Query Parameters

Example Request

Get Version by Number

Path Parameters

Example Request

Create Version

Request Body (multipart/form-data)

Example Request

Update Version

Path Parameters

Request Body

Example Request

Delete Version

Path Parameters

Example Request

Upload File to Version

Path Parameters

Request Body (multipart/form-data)

Common Use Cases

Getting Started

Core Resources

Content & Search

Server Hosting API

Client Libraries

​Get Version

​Path Parameters

​Response

​Example Request

​Example Response

​Get Multiple Versions

​Query Parameters

​Example Request

​Get Project Versions

​Path Parameters

​Query Parameters

​Example Request

​Get Version by Number

​Path Parameters

​Example Request

​Create Version

​Request Body (multipart/form-data)

​Example Request

​Update Version

​Path Parameters

​Request Body

​Example Request

​Delete Version

​Path Parameters

​Example Request

​Upload File to Version

​Path Parameters

​Request Body (multipart/form-data)

​Common Use Cases

Get Version

Path Parameters

Response

Example Request

Example Response

Get Multiple Versions

Query Parameters

Example Request

Get Project Versions

Path Parameters

Query Parameters

Example Request

Get Version by Number

Path Parameters

Example Request

Create Version

Request Body (multipart/form-data)

Example Request

Update Version

Path Parameters

Request Body

Example Request

Delete Version

Path Parameters

Example Request

Upload File to Version

Path Parameters

Request Body (multipart/form-data)

Common Use Cases