Query tool list

Lists the current workspace and system tools readable by the current identity. Lists do not return large input and output schemas by default; explicitly request the full view when needed.

GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools

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://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/tools?kind=http_api&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
query	string	No	Filter by tool properties.
status	string	No	Filter by tool properties.
kind	string	No	Filter by tool properties.
category	string	No	Filter by tool properties.
phase	string	No	Filter by tool properties.
side_effect_class	string	No	Filter by tool properties.
runtime	string	No	Filter by runtime visibility, binding type, or directory.
binding_type	string	No	Filter by runtime visibility, binding type, or directory.
catalog	string	No	Filter by runtime visibility, binding type, or directory.
tags	string	No	Filter by tag; can be provided repeatedly.
include_schema	boolean	No	When true, the list items contain input_schema and output_schema.
view	string	No	full or detail when the list item contains Schema.
limit	integer	No	Returns the quantity and starting offset. If not provided, the default is 50, offset 0; limit has a maximum of 200.
offset	integer	No	Returns the quantity and starting offset. If not provided, the default is 50, offset 0; limit has a maximum of 200.

Successful response

Returns 200 on success.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "tool_01",
        "workspace_id": "ws_01",
        "name": "查询工具",
        "display_name": "查询工具",
        "status": "active",
        "kind": "http_api",
        "side_effect_class": "read",
        "version": 1,
        "bindable": true,
        "supported_runtimes": []
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.items	array	Tools matching filter criteria.
data.items[].id	string	Tool, owning workspace and original name.
data.items[].workspace_id	string	Tool, owning workspace and original name.
data.items[].name	string	Tool, owning workspace and original name.
data.items[].description	string	Tool description; does not return if not set.
data.items[].display_name	string	The name and description of the projection in the current language.
data.items[].display_description	string	The name and description of the projection in the current language.
data.items[].status	string	Tool status, category and side effect classification.
data.items[].kind	string	Tool status, category and side effect classification.
data.items[].side_effect_class	string	Tool status, category and side effect classification.
data.items[].category	string	Tool classification; does not return if not set.
data.items[].source_ref	object	Tool source reference; not returned if not set.
data.items[].sync	object	Synchronization status; does not return if not set.
data.items[].version	integer	Tool version.
data.items[].bindable	boolean	Current binding capabilities and supported operating environments.
data.items[].bindability_reason	string	Current binding capabilities and supported operating environments.
data.items[].supported_runtimes	string[]	Current binding capabilities and supported operating environments.
data.items[].input_schema	object	Returned only if include_schema=true or view=full/detail.
data.items[].output_schema	object	Returned only if include_schema=true or view=full/detail.
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 matches, current page size, and offset.
data.limit	integer	Total number of matches, current page size, and offset.
data.offset	integer	Total number of matches, current page size, and offset.

[] 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 filter or paging parameters.	Check 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 tool directory.	Check workspace authorization.
503	15（UNAVAILABLE）	Tool resource services or authorization dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Save the identification of the target item and then Query tool details.

Last updated on Sep 3, 2026