查看文件列表¶

按卷筛选并分页查询文件。请求必须包含且只能包含一个 volume_id 筛选条件。

POST https://moi.matrixorigin.cn/newmoi/catalog/file/list

调用前准备¶

先查询数据库中的对象取得目标卷 ID。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和卷 ID。调用者需要目标根卷的读取权限。

请求体¶

请求示例

curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/file/list" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": [
      {
        "name": "volume_id",
        "values": ["'"$VOLUME_ID"'"]
      }
    ],
    "page": 1,
    "page_size": 20
  }'

参数说明

本文中，类型后的 [] 表示数组，例如 string[] 是字符串数组；字段路径中的 [] 表示数组中的每一项，例如 filters[].name 表示 filters 数组中每一项的 name 字段。

请求体

字段	类型	必填	说明
`filters`	array	是	筛选条件数组，必须包含一个 `name` 为 `volume_id` 的条件。
`page`	integer	否	页码。
`page_size`	integer	否	每页条数。
`order`	string	否	排序方向：`asc` 或 `desc`。
`order_by`	string	否	排序字段。

filters 项

下面表格展开请求中 filters 数组的每一项；每一行是该数组项的一个字段。

字段	类型	必填	说明
`name`	string	是	筛选字段名。`volume_id` 必须出现一次。
`values`	array[string]	是	筛选值。`volume_id` 必须为单个正整数值。
`fuzzy`	boolean	否	`name` 为 `file_name` 时，是否使用模糊匹配。

成功响应¶

成功时返回 200 和文件列表。调用者需要目标根卷的读取权限。

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 1,
    "list": [
      {
        "id": "file-123",
        "name": "orders.csv",
        "file_type": "file",
        "file_ext": "csv",
        "size": 2048,
        "parent_id": "",
        "volume_id": "789",
        "volume_name": "sales_files",
        "created_at": "2026-01-01T00:00:00Z"
      }
    ]
  }
}

字段说明

通用字段

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。

查询结果

下面表格展开响应示例中 data 对象；每一行是该对象的一个字段。

字段	类型	说明
`total`	integer	匹配筛选条件的条目总数。
`list`	object（对象数组）	文件和文件夹条目列表。

文件和文件夹

下面表格展开响应示例中 data.list 数组的每一项；每一行是该数组项的一个字段。

字段	类型	说明
`id`	string	条目 ID。
`name`	string	条目名称。
`file_path`	string	导入来源的稳定相对路径；有值时返回。
`file_type`	string	条目类型：`file` 或 `folder`。
`workflow_role`	string	工作流产物角色；工作流输出为 `output`，其他条目为空字符串。
`file_ext`	string	文件扩展名。
`origin_file_name`	string	原始文件名；适用时返回。
`origin_file_ext`	string	原始文件扩展名；适用时返回。
`size`	integer	文件大小，单位为字节。
`parent_id`	string	父级 ID。
`volume_id`	string	所属卷 ID。
`volume_name`	string	所属卷名称。
`volume_reserved`	boolean	所属卷是否为保留卷。
`created_at`	string	创建时间，采用 RFC 3339 格式。
`created_by`	string	创建者标识。
`ref_file_id`	string	关联的源文件 ID；适用时返回。
`parsed_file_id`	string	可下载解析产物的文件 ID；适用时返回。
`ref_workflow_id`	string	关联工作流 ID；适用时返回。

错误响应¶

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "必须提供唯一的 volume_id 筛选条件",
  "data": null
}

字段说明

字段	类型	说明
`code`	string	错误代码。
`msg`	string	错误信息。
`data`	null	错误响应中的附加数据；本示例为 `null`。

后续操作¶

使用 data.list[].id 查询文件详情。

最后更新于 2026 年 9 月 3 日