REST API endpoints for Project Versions

Create a project version

POST/projects/{projectId}/versions

Create a version with uploaded files or external file URLs.

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 BodyContent-Type: multipart/form-data

data is a JSON string containing the version metadata. File parts must be keyed by their filename, and each uploaded filename must appear in data.files.

data.channelstringRequired

Channel ID or slug.

data.versionstringRequired

Version identifier. Maximum 32 characters.

data.namestringRequired

Version display name. Maximum 64 characters.

data.filesarray<string>Required

Files of this version. Each item is either the name of an uploaded multipart file part (the part key must equal the filename; maximum 128 characters) or an external http(s) URL (maximum 256 characters).

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; duplicate identifiers are rejected.

typestringRequired

Relationship to this version. Values: required, optional, incompatible, embedded.

version_idstring

8-character ID of a specific version on Guizhan Resources.

project_idstring

8-character ID of a project. Any compatible version of the project satisfies the dependency.

namestring

External dependency display name. 1-64 visible characters. May be paired with url.

urlstring

HTTP(S) URL of the external dependency’s homepage or download page.

filesfile

Multipart file parts keyed by filename, referenced by data.files.

Response BodyContent-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. May be repeated to filter by multiple channels.

minecraft_versionstring

Filter by a Minecraft version. May be repeated to filter by multiple versions.

searchstring

Search versions by version string or display name.

Response BodyContent-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.

Query Parameters

idsstringRequired

Comma-separated version IDs to update.

Request BodyContent-Type: application/json

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.

typestringRequired

Relationship to this version. Values: required, optional, incompatible, embedded.

version_idstring

8-character ID of a specific version on Guizhan Resources.

project_idstring

8-character ID of a project. Any compatible version of the project satisfies the dependency.

namestring

External dependency display name. 1-64 visible characters. May be paired with url.

urlstring

HTTP(S) URL of the external dependency’s homepage or download page.

add_dependenciesarray<object>

Dependencies to add.

typestringRequired

Relationship to this version. Values: required, optional, incompatible, embedded.

version_idstring

8-character ID of a specific version on Guizhan Resources.

project_idstring

8-character ID of a project. Any compatible version of the project satisfies the dependency.

namestring

External dependency display name. 1-64 visible characters. May be paired with url.

urlstring

HTTP(S) URL of the external dependency’s homepage or download page.

remove_dependenciesarray<object>

Dependencies to remove.

typestringRequired

Relationship to this version. Values: required, optional, incompatible, embedded.

version_idstring

8-character ID of a specific version on Guizhan Resources.

project_idstring

8-character ID of a project. Any compatible version of the project satisfies the dependency.

namestring

External dependency display name. 1-64 visible characters. May be paired with url.

urlstring

HTTP(S) URL of the external dependency’s homepage or download page.

Response BodyContent-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.

Query Parameters

idsstringRequired

Comma-separated 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 BodyContent-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 BodyContent-Type: multipart/form-data

data is a JSON string containing optional version metadata and file changes. File parts must be keyed by their filename, and each uploaded filename must appear in 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.

typestringRequired

Relationship to this version. Values: required, optional, incompatible, embedded.

version_idstring

8-character ID of a specific version on Guizhan Resources.

project_idstring

8-character ID of a project. Any compatible version of the project satisfies the dependency.

namestring

External dependency display name. 1-64 visible characters. May be paired with url.

urlstring

HTTP(S) URL of the external dependency’s homepage or download page.

data.filesarray<string>

Files to add, replace, or remove. Each item is either the name of an uploaded multipart file part (the part key must equal the filename) or an external http(s) URL.

filesfile

Multipart file parts keyed by filename, referenced by data.files.

Response BodyContent-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 BodyContent-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 BodyContent-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.