Managing Versions

Upload, update, and manage versions of your Modrinth projects

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 Status

status · string

Requested version status

Options:

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

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

ordering · integer

Display order relative to other versions

Lower 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 'file=@mod-1.1.0.jar'

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

1. Use semantic versioning - Makes it clear what type of changes are included
2. Write detailed changelogs - Help users understand what’s new
3. Test before release - Use beta/alpha channels for untested changes
4. Mark dependencies - Help users install required mods
5. Support multiple versions - Release for current and recent game versions
6. Feature important versions - Highlight your recommended version
7. 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