查询工具列表

列出当前工作区和当前身份可读取的系统工具。列表默认不返回大型输入、输出 Schema；需要时显式请求完整视图。

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

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求参数

调用示例

curl "https://api.moi.matrixorigin.cn/v5/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"

参数说明

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。

查询参数

参数	类型	是否必填	说明
query	string	否	按工具属性筛选。
status	string	否	按工具属性筛选。
kind	string	否	按工具属性筛选。
category	string	否	按工具属性筛选。
phase	string	否	按工具属性筛选。
side_effect_class	string	否	按工具属性筛选。
runtime	string	否	按运行时可见性、绑定类型或目录筛选。
binding_type	string	否	按运行时可见性、绑定类型或目录筛选。
catalog	string	否	按运行时可见性、绑定类型或目录筛选。
tags	string	否	按标签筛选；可重复提供。
include_schema	boolean	否	为 true 时，列表项包含 input_schema 和 output_schema。
view	string	否	full 或 detail 时，列表项包含 Schema。
limit	integer	否	返回数量和起始偏移。未提供时默认 50 条、偏移 0；limit 最大 200。
offset	integer	否	返回数量和起始偏移。未提供时默认 50 条、偏移 0；limit 最大 200。

成功响应

响应示例

{
  "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
  }
}

字段说明

成功时返回 200。

响应字段如下。

本文中，字段路径中的 [] 表示数组中的每一项。例如，items[].name 表示 items 数组中每一项的 name 字段。

通用字段

字段	类型	说明
code	integer	成功时为 0。

基本信息

字段	类型	说明
items	array	匹配筛选条件的工具。
total	integer	匹配总数、当前页大小和偏移量。
limit	integer	匹配总数、当前页大小和偏移量。
offset	integer	匹配总数、当前页大小和偏移量。

列表项

下面表格展开响应示例中的 items 数据；每一行是该对象或数组项的一个字段。

字段	类型	说明
id	string	工具、所属工作区和原始名称。
workspace_id	string	工具、所属工作区和原始名称。
name	string	工具、所属工作区和原始名称。
description	string	工具说明；未设置时不返回。
display_name	string	按当前语言投影的名称和说明。
display_description	string	按当前语言投影的名称和说明。
status	string	工具状态、类别和副作用分类。
kind	string	工具状态、类别和副作用分类。
side_effect_class	string	工具状态、类别和副作用分类。
category	string	工具分类；未设置时不返回。
source_ref	object	工具来源引用；未设置时不返回。
sync	object	同步状态；未设置时不返回。
version	integer	工具版本。
bindable	boolean	当前绑定能力及支持的运行环境。
bindability_reason	string	当前绑定能力及支持的运行环境。
supported_runtimes	array of string	当前绑定能力及支持的运行环境。
input_schema	object	仅 include_schema=true 或 view=full/detail 时返回。
output_schema	object	仅 include_schema=true 或 view=full/detail 时返回。
created_by	string	创建者标识；未设置时不返回。
updated_by	string	最近更新者标识；未设置时不返回。
created_at	string	创建时间，采用 RFC 3339 格式。
updated_at	string	最近更新时间，采用 RFC 3339 格式。

错误响应

响应示例

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

字段说明

常见 HTTP 错误

通用字段

字段	类型	说明
400	2（INVALID_ARGUMENT）	**常见原因：**筛选或分页参数无效。**建议操作：**检查查询参数。
401	6（UNAUTHENTICATED）	**常见原因：**缺少有效身份凭据。**建议操作：**检查 API Key。
403	5（PERMISSION_DENIED）	**常见原因：**当前身份没有读取工具目录的权限。**建议操作：**检查工作区授权。
503	15（UNAVAILABLE）	**常见原因：**工具资源服务或授权依赖暂不可用。**建议操作：**稍后重试。

后续操作

保存目标项的标识，再查询工具详情。

最后更新于 2026 年 9 月 28 日