Skip to main content

Skill API overview

The Skill API manages Skills in Model Studio, including Skill creation, queries, deletion, and version management.

The Skill API manages Skills in Alibaba Cloud Model Studio. It covers creating, querying, and deleting custom and official Skills, as well as uploading, querying, and downloading versions.
Configure authentication before calling the API. For error handling, see Skill API error codes.

Prerequisites

  1. Alibaba Cloud Model Studio is activated, and an API key is created.
  2. A workspace ID is available. Log on to the Model Studio console, and copy the workspace ID from the workspace menu in the upper-right corner.

Endpoint

https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/skills
  • workspace_id: the workspace ID.

API list

APIMethodDescription
Create a SkillPOST /api/v1/skillsCreates a custom Skill from a ZIP package
Get a SkillGET /api/v1/skills/{skill_id}Gets a Skill
List SkillsGET /api/v1/skillsLists custom and official Skills with pagination
Delete a SkillDELETE /api/v1/skills/{skill_id}Deletes a custom Skill and all its versions
Create a versionPOST /api/v1/skills/{skill_id}/versionsUploads a new version for a custom Skill
List versionsGET /api/v1/skills/{skill_id}/versionsLists versions with pagination
Get version detailsGET /api/v1/skills/{skill_id}/versions/{version}Gets a version
Download a version ZIPGET /api/v1/skills/{skill_id}/versions/{version}/contentGets a temporary download URL for the ZIP package

Response structure

Successful responses and business errors share the following structure:
FieldTypeDescription
successbooleanWhether the request succeeded
error_codestring / nullError code. null on success
error_msgstring / nullError message. null on success
dataobject / array / nullBusiness data. null on failure
request_idstringRequest ID, also returned in the X-Request-Id response header
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {},
  "request_id": "15a89d4c-f142-4e00-a9f7-b088442417c9"
}

Pagination

The Skill list and version list use page-based pagination.
ParameterTypeDefaultDescription
pageNointeger1Page number. Minimum 1
pageSizeinteger20Number of items per page. Valid values: 1 to 100
pageNo × pageSize cannot exceed 10000. The response returns total, page_no, and page_size.

Enumerations

status
ValueDescription
checkingSecurity scanning in progress. Not available
activeAvailable
rejectedFailed the security scan. Not available
deletedDeleted. Not returned by normal queries
source
ValueDescription
customerCustom Skill under the primary account and workspace
officialOfficial Skill

Data structures

SkillDTO

Returned by create, get, and list operations.
FieldTypeDescription
idstringUnique Skill ID. Used as the skill_id path parameter
display_namestringDisplay name. If empty, the name in SKILL.md is used
display_descriptionstringDisplay description. If empty, the description in SKILL.md is used
sourcestringcustomer or official
statusstringSkill status. See the enumeration above
latest_versionstringLatest version number, such as 1.0
classificationstring / nullClassification. Set for official Skills; null for custom Skills
meta_infoobject / nullMetadata for official Skills; null for custom Skills
created_atstringCreation time in ISO 8601 UTC
updated_atstringUpdate time in ISO 8601 UTC

SkillVersionDTO

Returned by create version, list versions, and get version operations.
FieldTypeDescription
idstringUnique version ID. Prefixed with skillver_
typestringAlways skill_version
skill_idstringID of the parent Skill
display_namestringDisplay name of this version. If empty, the name in this version's SKILL.md is used
display_descriptionstringDisplay description of this version. If empty, the description in this version's SKILL.md is used
versionstringVersion number in major.minor format, such as 1.0 or 1.1
statusstringVersion status. See the enumeration above
created_atstringCreation time in ISO 8601 UTC
updated_atstringUpdate time in ISO 8601 UTC
additional_propertiesobject / nullAdditional properties. null if empty
additional_properties fields:
FieldTypeDescription
error_infomap<string,string> / nullDetails of a failed security scan. The key is a file path, and the value is the issue description

SkillDeletedResponse

FieldTypeDescription
idstringID of the deleted Skill
typestringAlways skill_deleted

VersionDownloadResponse

FieldTypeDescription
skill_idstringSkill ID
versionstringVersion number
file_urlstringPresigned download URL for the ZIP package. Valid for 2 hours

Page

The data structure of the Skill list and version list.
FieldTypeDescription
itemsarrayRecords on the current page
totallongTotal number of matching records
page_nointegerCurrent page number
page_sizeintegerNumber of items per page

Visibility

APIs that access a resource by skill_id check visibility first. Invisible resources are treated as nonexistent.
ObjectCustom SkillOfficial Skill
SkillNot deleted under the primary account and workspaceNot deleted and active
VersionAll non-deleted versions, including checking and rejectedactive only