REST API endpoints for Project Versions

Create a project version

POST /projects/{projectId}/versions

Create a version with uploaded files or external file URLs. Uploaded files must be JAR or ZIP files and each file can be at most 500 MiB.

Authentication

Authentication is required.

Access token must have project:version:create scope. Organization-owned projects also require the project:version:create organization member permission.

Learn more about authentication

Path Parameters

projectIdstringRequired

The project ID or slug.

Request Body Content-Type: multipart/form-data

data is a JSON string containing the version metadata. File parts must use keys referenced by files[].name when uploading files.

data.channelstringRequired

Channel ID or slug.

data.versionstringRequired

Version identifier. Maximum 64 characters.

data.namestringRequired

Version display name. Maximum 64 characters.

data.filesarray<object>Required

File descriptors. Each item can reference an uploaded multipart file or an external URL.

data.changelogstring

Version changelog in Markdown.

data.minecraft_versionsarray<string>

Minecraft versions. Defaults to the channel values when omitted.

data.platformsarray<string>

Platforms. Values: bukkit, spigot, paper, folia, purpur, forge, fabric, quilt, neoforge, resourcepack, datapack, or other. Defaults to the channel values when omitted.

data.dependenciesarray<object>

Dependencies. Defaults to the channel values when omitted. Each dependency must reference exactly one of version_id, project_id, or name.

filesfile

Multipart file parts referenced by data.files.

Response Body Content-Type: application/json

This API endpoint returns standard API response format. The following fields are fields of the data object. Learn more

idstringRequired

The unique identifier of the version.

versionstringRequired

The version identifier.

namestringRequired

The display name of the version.

changelogstring

Version changelog in Markdown.

minecraft_versionsarray<string>

Minecraft versions supported by this version.

platformsarray<string>Required

Platforms supported by this version.

dependenciesarray<object>Required

Dependencies for this version.

typestringRequired

Dependency type. One of required, optional, incompatible, or embedded.

version_idstring

Target version ID.

project_idstring

Target project ID.

namestring

External dependency name.

urlstring

External dependency URL.

downloadsnumberRequired

Download count for this version.

created_atstringRequired

ISO 8601 timestamp of when the version was created.

channelobjectRequired

The channel that contains this version.

idstringRequired

The unique identifier of the channel.

namestringRequired

The display name of the channel.

slugstringRequired

The channel slug.

is_defaultbooleanRequired

Whether this is the default channel.

last_slug_updated_atstring

ISO 8601 timestamp of the last channel slug update.

filesarray<object>Required

Files attached to the version.

idstringRequired

The unique identifier of the file.

namestringRequired

The file name or external URL.

checksumobject

File checksums for uploaded files.

sizenumber

File size in bytes for uploaded files.

external_urlstring

External download URL when the file is not stored by the API.

is_primarybooleanRequired

Whether this is the primary file for the version.

created_atstringRequired

ISO 8601 timestamp of when the file was created.

List project versions

GET /projects/{projectId}/versions

Path Parameters

projectIdstringRequired

The project ID or slug.

Query Parameters

pagenumber

Page number. Defaults to 1.

page_sizenumber

Items per page.

channelstring

Filter by channel ID or slug.

minecraft_versionsarray<string>

Filter by Minecraft versions.

platformsarray<string>

Filter by platforms.

Response Body Content-Type: application/json

This API endpoint returns standard API response format. The following fields are fields of the data object. Learn more

idstringRequired

The unique identifier of the version.

versionstringRequired

The version identifier.

namestringRequired

The display name of the version.

changelogstring

Version changelog in Markdown.

minecraft_versionsarray<string>

Minecraft versions supported by this version.

platformsarray<string>Required

Platforms supported by this version.

dependenciesarray<object>Required

Dependencies for this version.

typestringRequired

Dependency type. One of required, optional, incompatible, or embedded.

version_idstring

Target version ID.

project_idstring

Target project ID.

namestring

External dependency name.

urlstring

External dependency URL.

downloadsnumberRequired

Download count for this version.

created_atstringRequired

ISO 8601 timestamp of when the version was created.

channelobjectRequired

The channel that contains this version.

idstringRequired

The unique identifier of the channel.

namestringRequired

The display name of the channel.

slugstringRequired

The channel slug.

is_defaultbooleanRequired

Whether this is the default channel.

last_slug_updated_atstring

ISO 8601 timestamp of the last channel slug update.

Batch update project versions

PATCH /projects/{projectId}/versions

Apply the same metadata changes to multiple versions. Direct set operations cannot be combined with add/remove operations for the same field.

Authentication

Authentication is required.

Access token must have project:version:update scope. Organization-owned projects also require the project:version:update organization member permission.

Learn more about authentication

Path Parameters

projectIdstringRequired

The project ID or slug.

Request Body Content-Type: application/json

versionsarray<string>Required

Version IDs to update.

channelstring

New channel ID or slug.

namestring

New display name.

changelogstring

New changelog in Markdown.

minecraft_versionsarray<string>

Replace Minecraft versions.

add_minecraft_versionsarray<string>

Minecraft versions to add.

remove_minecraft_versionsarray<string>

Minecraft versions to remove.

platformsarray<string>

Replace platforms. Values: bukkit, spigot, paper, folia, purpur, forge, fabric, quilt, neoforge, resourcepack, datapack, or other.

add_platformsarray<string>

Platforms to add.

remove_platformsarray<string>

Platforms to remove.

dependenciesarray<object>

Replace dependencies.

add_dependenciesarray<object>

Dependencies to add.

remove_dependenciesarray<object>

Dependencies to remove.

Response Body Content-Type: application/json

This API endpoint returns standard API response format. The following fields are fields of the data object. Learn more

idstringRequired

The unique identifier of the version.

versionstringRequired

The version identifier.

namestringRequired

The display name of the version.

changelogstring

Version changelog in Markdown.

minecraft_versionsarray<string>

Minecraft versions supported by this version.

platformsarray<string>Required

Platforms supported by this version.

dependenciesarray<object>Required

Dependencies for this version.

typestringRequired

Dependency type. One of required, optional, incompatible, or embedded.

version_idstring

Target version ID.

project_idstring

Target project ID.

namestring

External dependency name.

urlstring

External dependency URL.

downloadsnumberRequired

Download count for this version.

created_atstringRequired

ISO 8601 timestamp of when the version was created.

channelobjectRequired

The channel that contains this version.

idstringRequired

The unique identifier of the channel.

namestringRequired

The display name of the channel.

slugstringRequired

The channel slug.

is_defaultbooleanRequired

Whether this is the default channel.

last_slug_updated_atstring

ISO 8601 timestamp of the last channel slug update.

filesarray<object>Required

Files attached to the version.

idstringRequired

The unique identifier of the file.

namestringRequired

The file name or external URL.

checksumobject

File checksums for uploaded files.

sizenumber

File size in bytes for uploaded files.

external_urlstring

External download URL when the file is not stored by the API.

is_primarybooleanRequired

Whether this is the primary file for the version.

created_atstringRequired

ISO 8601 timestamp of when the file was created.

Batch delete project versions

DELETE /projects/{projectId}/versions

Authentication

Authentication is required.

Access token must have project:version:delete scope. Organization-owned projects also require the project:version:delete organization member permission.

Learn more about authentication

Path Parameters

projectIdstringRequired

The project ID or slug.

Request Body Content-Type: application/json

versionsarray<string>Required

Version IDs to delete.

Get a project version

GET /projects/{projectId}/versions/{versionId}

Path Parameters

projectIdstringRequired

The project ID or slug.

versionIdstringRequired

The version ID or version string.

Response Body Content-Type: application/json

This API endpoint returns standard API response format. The following fields are fields of the data object. Learn more

idstringRequired

The unique identifier of the version.

versionstringRequired

The version identifier.

namestringRequired

The display name of the version.

changelogstring

Version changelog in Markdown.

minecraft_versionsarray<string>

Minecraft versions supported by this version.

platformsarray<string>Required

Platforms supported by this version.

dependenciesarray<object>Required

Dependencies for this version.

typestringRequired

Dependency type. One of required, optional, incompatible, or embedded.

version_idstring

Target version ID.

project_idstring

Target project ID.

namestring

External dependency name.

urlstring

External dependency URL.

downloadsnumberRequired

Download count for this version.

created_atstringRequired

ISO 8601 timestamp of when the version was created.

channelobjectRequired

The channel that contains this version.

idstringRequired

The unique identifier of the channel.

namestringRequired

The display name of the channel.

slugstringRequired

The channel slug.

is_defaultbooleanRequired

Whether this is the default channel.

last_slug_updated_atstring

ISO 8601 timestamp of the last channel slug update.

filesarray<object>Required

Files attached to the version.

idstringRequired

The unique identifier of the file.

namestringRequired

The file name or external URL.

checksumobject

File checksums for uploaded files.

sizenumber

File size in bytes for uploaded files.

external_urlstring

External download URL when the file is not stored by the API.

is_primarybooleanRequired

Whether this is the primary file for the version.

created_atstringRequired

ISO 8601 timestamp of when the file was created.

Update a project version

PATCH /projects/{projectId}/versions/{versionId}

Authentication

Authentication is required.

Access token must have project:version:update scope. Organization-owned projects also require the project:version:update organization member permission.

Learn more about authentication

Path Parameters

projectIdstringRequired

The project ID or slug.

versionIdstringRequired

The version ID or version string.

Request Body Content-Type: multipart/form-data

data is a JSON string containing optional version metadata and file changes. Uploaded file parts must use keys referenced by data.files.

data.channelstring

Channel ID or slug.

data.versionstring

Version identifier.

data.namestring

Version display name.

data.changelogstring

Version changelog in Markdown.

data.minecraft_versionsarray<string>

Minecraft versions.

data.platformsarray<string>

Platforms. Values: bukkit, spigot, paper, folia, purpur, forge, fabric, quilt, neoforge, resourcepack, datapack, or other.

data.dependenciesarray<object>

Dependencies.

data.filesarray<object>

File descriptors to add, replace, or remove.

filesfile

Multipart file parts referenced by data.files.

Response Body Content-Type: application/json

This API endpoint returns standard API response format. The following fields are fields of the data object. Learn more

idstringRequired

The unique identifier of the version.

versionstringRequired

The version identifier.

namestringRequired

The display name of the version.

changelogstring

Version changelog in Markdown.

minecraft_versionsarray<string>

Minecraft versions supported by this version.

platformsarray<string>Required

Platforms supported by this version.

dependenciesarray<object>Required

Dependencies for this version.

typestringRequired

Dependency type. One of required, optional, incompatible, or embedded.

version_idstring

Target version ID.

project_idstring

Target project ID.

namestring

External dependency name.

urlstring

External dependency URL.

downloadsnumberRequired

Download count for this version.

created_atstringRequired

ISO 8601 timestamp of when the version was created.

channelobjectRequired

The channel that contains this version.

idstringRequired

The unique identifier of the channel.

namestringRequired

The display name of the channel.

slugstringRequired

The channel slug.

is_defaultbooleanRequired

Whether this is the default channel.

last_slug_updated_atstring

ISO 8601 timestamp of the last channel slug update.

filesarray<object>Required

Files attached to the version.

idstringRequired

The unique identifier of the file.

namestringRequired

The file name or external URL.

checksumobject

File checksums for uploaded files.

sizenumber

File size in bytes for uploaded files.

external_urlstring

External download URL when the file is not stored by the API.

is_primarybooleanRequired

Whether this is the primary file for the version.

created_atstringRequired

ISO 8601 timestamp of when the file was created.

Delete a project version

DELETE /projects/{projectId}/versions/{versionId}

Authentication

Authentication is required.

Access token must have project:version:delete scope. Organization-owned projects also require the project:version:delete organization member permission.

Learn more about authentication

Path Parameters

projectIdstringRequired

The project ID or slug.

versionIdstringRequired

The version ID or version string.

Download a version file

GET /projects/{projectId}/versions/{versionId}/download/{fileId}

Redirects to the requested file download. If fileId is omitted, the primary file is downloaded.

Path Parameters

projectIdstringRequired

The project ID or slug.

versionIdstringRequired

The version ID or version string.

fileIdstring

Optional file ID.

Response Body Content-Type: redirect

Returns a redirect to the stored file or external URL.

Get a version directly

GET /versions/{versionId}

Path Parameters

versionIdstringRequired

The version ID.

Response Body Content-Type: application/json

This API endpoint returns standard API response format. The following fields are fields of the data object. Learn more

idstringRequired

The unique identifier of the version.

versionstringRequired

The version identifier.

namestringRequired

The display name of the version.

changelogstring

Version changelog in Markdown.

minecraft_versionsarray<string>

Minecraft versions supported by this version.

platformsarray<string>Required

Platforms supported by this version.

dependenciesarray<object>Required

Dependencies for this version.

typestringRequired

Dependency type. One of required, optional, incompatible, or embedded.

version_idstring

Target version ID.

project_idstring

Target project ID.

namestring

External dependency name.

urlstring

External dependency URL.

downloadsnumberRequired

Download count for this version.

created_atstringRequired

ISO 8601 timestamp of when the version was created.

channelobjectRequired

The channel that contains this version.

idstringRequired

The unique identifier of the channel.

namestringRequired

The display name of the channel.

slugstringRequired

The channel slug.

is_defaultbooleanRequired

Whether this is the default channel.

last_slug_updated_atstring

ISO 8601 timestamp of the last channel slug update.

filesarray<object>Required

Files attached to the version.

idstringRequired

The unique identifier of the file.

namestringRequired

The file name or external URL.

checksumobject

File checksums for uploaded files.

sizenumber

File size in bytes for uploaded files.

external_urlstring

External download URL when the file is not stored by the API.

is_primarybooleanRequired

Whether this is the primary file for the version.

created_atstringRequired

ISO 8601 timestamp of when the file was created.

project_idstringRequired

The project ID that owns this version.