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
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| skill_id | Path | string | Yes | ID of a custom Skill under the primary account and workspace |
| file | Form | file | Yes | New version ZIP package. Requirements are the same as Create a Skill |
| display_name | Form | string | No | Updates the Skill display name. If omitted or blank, the name in the new package's SKILL.md is used |
| display_description | Form | string | No | Updates 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. Therejectedstatus can be re-uploaded. - The
namein 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_versionpoints to the new version. Old versions are retained. - The
display_nameanddisplay_descriptionrequest fields update the Skill display information.
Response
Returns a SkillVersionDTO for the new version.
| Field | Type | Description |
|---|---|---|
| id | string | Unique version ID |
| type | string | Always skill_version |
| skill_id | string | ID of the parent Skill |
| display_name | string | Display name of the version |
| display_description | string | Display description of the version |
| version | string | Version number |
| status | string | Version status |
| created_at | string | Creation time |
| updated_at | string | Update time |
| additional_properties | object / null | Additional properties |
Example
Errors
| HTTP status | error_code | Description |
|---|---|---|
| 401 | WORKSPACE_ID_ILLEGAL | Identity information is missing or invalid |
| 400 | SKILL_ID_IS_NULL | skill_id is blank |
| 400 | SKILL_FILE_IS_NULL | file is not uploaded or the file is empty |
| 400 | SKILL_FILE_FORMATER_ERROR | The file extension is not .zip, or the file header is not in ZIP format |
| 400 | SKILL_PACKAGE_TOO_LARGE | The ZIP package exceeds 50MB |
| 400 | INVALID_PARAMETER | The multipart request is malformed |
| 500 | SKILL_NOT_EXIST | The Skill does not exist, is deleted, or is inaccessible |
| 500 | SKILL_VERSION_NOT_EXIST | The version record could not be read after it was saved |
| 500 | SKILL_UPDATE_SECURITY_ERROR | The Skill is being security scanned |
| 500 | SKILL_NAME_OFFICIAL_DUPLICATE | The new package's name duplicates an official Skill |
| 500 | SKILL_NAME_CUSTOMER_DUPLICATE | The new package's name duplicates another custom Skill in the current workspace |
| 500 | SKILL_UPDATE_LOCK_ERROR | A concurrent version creation conflicts on the same Skill |