Query skill list

Lists current workspace skills and readable system default skills. The system skill workspace_id is system and should be considered a read-only resource.

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

Before you call

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

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

• $WORKSPACE_ID: The workspace ID to be queried is passed through the X-Workspace-ID Header.

Request example

curl "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/skills?status=active&limit=20&offset=0" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Path parameters

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

Query parameters

Parameters	Type	Is it required	Description
status	string	No	Filter by skill status.
source_type	string	No	Filter by source type, such as custom or system.
category	string	No	Filter by skill category.
phase	string	No	Filter by skill stage.
query	string	No	Search by skill text.
tags	array of string	No	Repeat to filter tags, for example tags=text-processing&tags=summary.
limit	integer	No	Quantity per page. Default 50, maximum 200.
offset	integer	No	Starting offset; negative numbers are treated as 0.

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

Successful response

Returns 200 on success.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "skill_01",
        "workspace_id": "ws_01",
        "name": "摘要技能",
        "description": "总结输入内容。",
        "status": "active",
        "source_type": "custom",
        "version": 2
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.items	array	Skill definitions returned on the current page.
data.items[].id	string	Skill ID.
data.items[].workspace_id	string	Workspace where the skill belongs; system for system skills.
data.items[].name	string	Skill name.
data.items[].status	string	Skill status.
data.items[].source_type	string	Skill source type.
data.items[].description	string	Skill description; does not return if not set.
data.items[].source_ref	string	Source reference; not returned if not set.
data.items[].category	string	Skill classification; does not return if not set.
data.items[].tags	array of string	Skill labels; does not return if not set.
data.items[].phase	string	Skill stage; does not return if not set.
data.items[].routing_summary	object	Route summary; not returned if not set.
data.items[].instruction	object	Skill command.
data.items[].requirements	object	Skill dependency requirements; not returned if not set.
data.items[].version	integer	Current version.
data.items[].metadata	object	Extended metadata; not returned if not set.
data.items[].created_by	string	Creator ID; does not return if not set.
data.items[].updated_by	string	Last updater ID; does not return if not set.
data.items[].created_at	string	Creation time, in RFC 3339 format.
data.items[].updated_at	string	Last updated time, in RFC 3339 format.
data.total	integer	Total number of matching skills.
data.limit	integer	Maximum number of skills requested for this page.
data.offset	integer	Zero-based offset of the first skill 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 workspace or filter 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 workspace skills.	Check workspace authorization.
503	15（UNAVAILABLE）	Skill services or authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Save the identification of the target skill and then Query skill details.

Last updated on Oct 19, 2026