Versions API

API endpoints for managing project versions and files

Get Version

Retrieve a single version by its ID.

GET /v3/version/{id}

Path Parameters

id · string · required

The version ID

Response

id · 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 · 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 'file=@my-mod-1.0.0.jar'

---

Update Version

Update version metadata. Requires authentication and VERSION_WRITE scope.

PATCH /v3/version/{id}

Path Parameters

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

id · 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 · file · required

The file to upload

---

Common Use Cases

Publishing a New Version

1. Prepare version metadata (name, version number, changelog)
2. Build and test your mod/modpack files
3. Create version via POST /v3/version with multipart form data
4. 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