Managing Versions

Versions are the individual releases of your project that users download. This guide covers creating versions, managing files, and handling dependencies.

Version Overview

Each version represents a specific release of your project with:

One or more downloadable files
Version metadata (number, changelog, etc.)
Loader and game compatibility information
Dependencies and relationships to other projects
Release channel (release, beta, alpha)

Creating a New Version

Version Information

ID or slug of the project to add the version toYou must have UPLOAD_VERSION permission on the project.

Unique version identifier (1-32 characters, URL-safe)Common formats:

Semantic versioning: 1.0.0, 2.1.3
With build metadata: 1.0.0+fabric
With pre-release: 1.0.0-beta.1

Must be unique within your project.

Display name for this version (1-64 characters)Examples:

“Initial Release”
“Bug Fix Update”
“Christmas Update 2024”

Changelog in Markdown (up to 65,536 characters)Describe what’s new, changed, or fixed in this version.Example:

## Changes
- Added new feature X
- Fixed bug with Y
- Improved performance of Z

## Known Issues
- Issue with compatibility on version A

Release typeOptions:

release - Stable release
beta - Beta/preview release
alpha - Early alpha/experimental release

Users can filter by channel when searching for versions.

Loaders and Compatibility

Mod loaders this version supports (at least 1 required)Common loaders:

fabric - Fabric mod loader
forge - Forge mod loader
quilt - Quilt mod loader
neoforge - NeoForge mod loader
paper - Paper server platform
spigot - Spigot server platform
bungeecord - BungeeCord proxy
velocity - Velocity proxy

Get full list:

GET /v3/tag/loader

Loader-specific fields (flattened in JSON)Each loader has required fields, typically:game_versions (required for most loaders) Array of game versions this supports:

{
  "game_versions": ["1.20.1", "1.20.2", "1.20.3"]
}

Get available versions for a loader:

GET /v3/loader_field?loader_field=game_versions&filters={"loader":"fabric"}

Other common fields:

singleplayer - Singleplayer compatibility (boolean)
client_and_server - Client and server mode (string)
client_only - Client-only mod (boolean)
server_only - Server-only mod (boolean)

Missing required loader fields will cause validation errors. Each loader may have different required fields.

File Uploads

Multipart field names for files to uploadEach entry corresponds to a file field in the multipart request.Example:

"file_parts": ["primary-file", "optional-file"]

File requirements:

Maximum size: 500 MiB per file (contact moderators for larger files)

Supported formats: .jar, .zip, .mrpack, and other project-specific formats

File naming: No slashes (/) allowed in filenames

Duplicates: File hash must not exist in other projects

Field name of the primary/main fileThe primary file is:

Downloaded by default
Shown prominently in the UI
Used by modpack launchers

If not specified, the first valid file becomes primary.

Optional file type overridesSpecify types for each file:

{
  "primary-file": "required-resource-pack",
  "optional-file": "optional-resource-pack"
}

Types:

required-resource-pack
optional-resource-pack
No type specified = automatic detection

File Validation

Uploaded files undergo automatic validation:

Hash checking - Prevents duplicate uploads

Format validation - Ensures files are valid for their type

Security scanning - Checks for malware and malicious code

Dependency extraction - Automatically detects embedded dependencies in modpacks

If a file fails validation but you believe it’s safe, warnings can be overridden by not marking it as primary. Only primary files with warnings will block the upload.

Dependencies

Project dependencies (up to 4,096 dependencies)Each dependency specifies:

{
  "project_id": "P7dR8mSH",
  "version_id": "iG3U0CqT",
  "dependency_type": "required"
}

Dependency types:

required - Must be installed
optional - Recommended but not required
incompatible - Known conflict
embedded - Included in the file (auto-detected for modpacks)

For modpacks, dependencies are automatically extracted from pack files. Manually specified dependencies override auto-detection.

Version Status

status

string

Requested version statusOptions:

listed - Visible and downloadable (default)
archived - Hidden from main view, still accessible
draft - Not publicly visible

Only statuses you have permission for can be requested.

featured

boolean

Feature this versionFeatured versions appear prominently on the project page. Only one version can be featured at a time.

ordering

integer

Display order relative to other versionsLower numbers appear first. If not specified, versions are ordered by publish date.

API Example: Creating a Version

curl -X POST https://api.modrinth.com/v3/version \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'data={
    "project_id": "my-project",
    "version_number": "1.1.0",
    "version_title": "Feature Update",
    "version_body": "## Added\n- New cool feature\n- Bug fixes",
    "loaders": [{"0": "fabric"}],
    "fields": {
      "game_versions": ["1.20.1", "1.20.2"]
    },
    "release_channel": "release",
    "file_parts": ["file"],
    "primary_file": "file",
    "featured": false,
    "dependencies": [
      {
        "project_id": "P7dR8mSH",
        "dependency_type": "required"
      }
    ]
  }' \
  -F '[email protected]'

Updating Versions

You can update version metadata after creation:

PATCH /v3/version/{id}

Updatable fields:

version_title - Display name
version_body - Changelog
status - Version status
featured - Featured status
ordering - Display order
loaders - Supported loaders (requires re-validation)
Loader fields (game versions, etc.)

Changing loaders or loader fields triggers re-validation of the version files.

Adding Files to Existing Versions

Add additional files to a version:

POST /v3/version/{id}/file

Multipart request with:

data - JSON with optional file_types map
File fields - The actual files to upload

All the same validation rules apply.

Version Channels

Use release channels to manage different release tracks:

Release

Stable, production-ready versions:

Recommended for most users
Should be well-tested
Default channel for downloads

Beta

Preview versions for testing:

May have known issues
Users opt-in to beta versions
Good for gathering feedback

Alpha

Experimental early versions:

Potentially unstable
For brave testers only
May have breaking changes

Users can filter by channel when browsing versions. Consider using semantic versioning with pre-release tags (e.g., 1.0.0-beta.1).

Deleting Versions

Versions can be deleted if:

You have DELETE_VERSION permission
The version is not the only version of the project

DELETE /v3/version/{id}

Deleting a version is permanent and cannot be undone. The version ID cannot be reused.

Notifications

When you publish a new version:

All project followers receive a notification
Notifications include project and version IDs
Users can customize their notification preferences

Best Practices

Use semantic versioning - Makes it clear what type of changes are included
Write detailed changelogs - Help users understand what’s new
Test before release - Use beta/alpha channels for untested changes
Mark dependencies - Help users install required mods
Support multiple versions - Release for current and recent game versions
Feature important versions - Highlight your recommended version
Archive old versions - Clean up very outdated releases

Troubleshooting

Common issues: File already exists

The file hash matches an existing file in another project
This prevents duplicate uploads across Modrinth

Invalid loader field

Required field missing for selected loader
Check required fields: GET /v3/tag/loader

File validation failed

File format is invalid or corrupted
File contains detected security issues
Contact moderators if you believe this is incorrect

Permission denied

You don’t have UPLOAD_VERSION permission
Ask a project owner to grant you permissions

Get Started

Platform Guide

For Creators

For Players

Server Hosting

Managing Versions

Version Overview

Creating a New Version

Version Status

API Example: Creating a Version

Updating Versions

Adding Files to Existing Versions

Version Channels

Release

Beta

Alpha

Deleting Versions

Notifications

Best Practices

Troubleshooting

Get Started

Platform Guide

For Creators

For Players

Server Hosting

​Version Overview

​Creating a New Version

​Version Status

​API Example: Creating a Version

​Updating Versions

​Adding Files to Existing Versions

​Version Channels

​Release

​Beta

​Alpha

​Deleting Versions

​Notifications

​Best Practices

​Troubleshooting

Version Overview

Creating a New Version

Version Status

API Example: Creating a Version

Updating Versions

Adding Files to Existing Versions

Version Channels

Release

Beta

Alpha

Deleting Versions

Notifications

Best Practices

Troubleshooting