Query skill version

Lists the skill’s version snapshot. This interface can explicitly read the skill version in the current workspace or system workspace.

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/skills/{skill_id}/versions

Before you call

First query the skill list to obtain the skill ID and the skill workspace. Save them as SKILL_ID and SKILL_WORKSPACE_ID; use system for system skills. Prepare the personal access token and target workspace ID.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.

• $SKILL_ID: Skill ID.

• $SKILL_WORKSPACE_ID: Workspace where the skill definition belongs; system for system skills.

Request example

curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/skills/$SKILL_ID/versions" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "skill_workspace_id=$SKILL_WORKSPACE_ID" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	The current workspace ID.
skill_id	string	Yes	Skill ID.

Query parameters

Parameters	Type	Is it required	Description
skill_workspace_id	string	No	Workspace where the skill belongs. Use workspace_id from the same skill-list item; use system for system skills. If omitted, the current workspace is used.
limit	integer	No	Quantity per page. Default 50, maximum 200.
offset	integer	No	Starting offset; negative numbers are treated as 0.

Successful response

Returns 200 on success.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "skill_ver_02",
        "workspace_id": "ws_01",
        "skill_id": "skill_01",
        "version": 2,
        "spec_snapshot": {
          "name": "摘要技能",
          "status": "active"
        },
        "change_summary": "补充输出约定",
        "created_at": "2026-01-03T10:00:00Z"
      }
    ],
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.items	array	Skill versions returned on the current page.
data.items[].id	string	Version record ID.
data.items[].skill_id	string	Skill ID for this version.
data.items[].workspace_id	string	Workspace where the skill belongs.
data.items[].version	integer	Skill version number.
data.items[].spec_snapshot	object	A snapshot of the complete skill definition when this version was saved.
data.items[].change_summary	string	Version change description; not returned if not set.
data.items[].created_at	string	Version creation time, in RFC 3339 format.
data.total	integer	Total number of matching versions.
data.limit	integer	Maximum number of versions requested for this page.
data.offset	integer	Zero-based offset of the first version in this page.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response

{
  "code": 2,
  "message": "<错误信息>"
}

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	Invalid skill ID, workspace range, or paging parameters.	Check path and query parameters.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to read the skill version.	Check workspace authorization.
404	3（NOT_FOUND）	The skill or version record does not exist in the specified workspace.	Check skill ID and skill_workspace_id.
503	15（UNAVAILABLE）	Skill services or authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations

After selecting the version, you can Set the current skill version; when you need skill subject information, Query skill details.

Last updated on Sep 11, 2026