Skip to main content

Create a version

Uploads a new version ZIP package for a custom Skill. The server increments the version number.

Endpoint

POST /api/v1/skills/{skill_id}/versions Uploads a new version for a custom Skill as multipart/form-data. The server increments the version number from latest_version. For example, 1.0 becomes 1.1. The version number cannot be specified.

Request parameters

ParameterLocationTypeRequiredDescription
skill_idPathstringYesID of a custom Skill under the primary account and workspace
fileFormfileYesNew version ZIP package. Requirements are the same as Create a Skill
display_nameFormstringNoUpdates the Skill display name. If omitted or blank, the name in the new package's SKILL.md is used
display_descriptionFormstringNoUpdates the Skill display description. If omitted or blank, the description in the new package's SKILL.md is used

Rules

  • Only custom Skills can have new versions.
  • A new version cannot be created while the Skill is being security scanned (checking). Wait for the scan to finish. The rejected status can be re-uploaded.
  • The name in the new package's SKILL.md cannot duplicate an official Skill or another custom Skill in the current workspace.
  • After creation, the Skill's latest_version points to the new version. Old versions are retained.
  • The display_name and display_description request fields update the Skill display information.

Response

Returns a SkillVersionDTO for the new version.
FieldTypeDescription
idstringUnique version ID
typestringAlways skill_version
skill_idstringID of the parent Skill
display_namestringDisplay name of the version
display_descriptionstringDisplay description of the version
versionstringVersion number
statusstringVersion status
created_atstringCreation time
updated_atstringUpdate time
additional_propertiesobject / nullAdditional properties

Example

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/skills/skill_abc123/versions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -F "file=@./pdf-skill-v2.zip"
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {
    "id": "skillver_xxxxxxxxxxxxxxxxxxxxxx",
    "type": "skill_version",
    "skill_id": "skill_abc123",
    "display_name": "My Custom Skill",
    "display_description": "Description parsed from SKILL.md",
    "version": "1.1",
    "status": "checking",
    "created_at": "2026-06-15T08:23:11Z",
    "updated_at": "2026-06-15T08:23:11Z",
    "additional_properties": null
  },
  "request_id": "15a89d4c-f142-4e00-a9f7-b088442417c9"
}

Errors

HTTP statuserror_codeDescription
401WORKSPACE_ID_ILLEGALIdentity information is missing or invalid
400SKILL_ID_IS_NULLskill_id is blank
400SKILL_FILE_IS_NULLfile is not uploaded or the file is empty
400SKILL_FILE_FORMATER_ERRORThe file extension is not .zip, or the file header is not in ZIP format
400SKILL_PACKAGE_TOO_LARGEThe ZIP package exceeds 50MB
400INVALID_PARAMETERThe multipart request is malformed
500SKILL_NOT_EXISTThe Skill does not exist, is deleted, or is inaccessible
500SKILL_VERSION_NOT_EXISTThe version record could not be read after it was saved
500SKILL_UPDATE_SECURITY_ERRORThe Skill is being security scanned
500SKILL_NAME_OFFICIAL_DUPLICATEThe new package's name duplicates an official Skill
500SKILL_NAME_CUSTOMER_DUPLICATEThe new package's name duplicates another custom Skill in the current workspace
500SKILL_UPDATE_LOCK_ERRORA concurrent version creation conflicts on the same Skill
For the full list, see Skill API error codes.