查询文件列表

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

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

调用前准备

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

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递。

• $VOLUME_ID：要列出文件的卷 ID，通过 filters 中的 volume_id 传递。

调用者需要目标根卷的读取权限。

请求体

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

参数	类型	是否必填	说明
filters	array	是	筛选条件数组，必须包含一个 name 为 volume_id 的条件。
filters[].name	string	是	筛选字段名。volume_id 必须出现一次。
filters[].values	array[string]	是	筛选值。volume_id 必须为单个正整数值。
filters[].fuzzy	boolean	否	name 为 file_name 时，是否使用模糊匹配。
page	integer	否	页码。
page_size	integer	否	每页条数。
order	string	否	排序方向：asc 或 desc。
order_by	string	否	排序字段。

请求示例

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
  }'

成功响应

成功时返回 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	匹配筛选条件的条目总数。
data.list	array	文件和文件夹条目列表。
data.list[].id	string	条目 ID。
data.list[].name	string	条目名称。
data.list[].file_type	string	条目类型：file 或 folder。
data.list[].workflow_role	string	工作流产物角色；工作流输出为 output，其他条目为空字符串。
data.list[].file_ext	string	文件扩展名。
data.list[].origin_file_name	string	原始文件名；适用时返回。
data.list[].origin_file_ext	string	原始文件扩展名；适用时返回。
data.list[].size	integer	文件大小，单位为字节。
data.list[].parent_id	string	父级 ID。
data.list[].volume_id	string	所属卷 ID。
data.list[].volume_name	string	所属卷名称。
data.list[].volume_reserved	boolean	所属卷是否为保留卷。
data.list[].created_at	string	创建时间，采用 RFC 3339 格式。
data.list[].created_by	string	创建者标识。
data.list[].ref_file_id	string	关联的源文件 ID；适用时返回。
data.list[].parsed_file_id	string	可下载解析产物的文件 ID；适用时返回。
data.list[].ref_workflow_id	string	关联工作流 ID；适用时返回。

错误响应

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

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	ErrParamInvalid	未传入唯一的正整数 volume_id 筛选条件。	在 filters 中仅保留一个 volume_id。
403	ErrForbidden	当前身份没有目标根卷读取权限。	检查工作区和卷授权。
404	ErrNotFound	目标卷不存在。	检查 volume_id。
500	ErrServer	服务无法读取文件列表。	记录请求时间和错误信息后重试；持续失败时联系支持人员。

后续操作

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

最后更新于 2026 年 8 月 22 日