Query file list¶

Filter by volume and query files by page. The request must contain exactly one volume_id filter. In the console volume file list, a folder is an entry whose file_type is folder.

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

Preparation before calling¶

First query the object in the database to obtain the target volume ID. Prepare the personal access token, target workspace ID, and volume ID that have 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: Target workspace ID, passed through X-Workspace-ID Header.
$VOLUME_ID: The volume ID of the file to be listed, passed via volume_id in filters.

The caller needs read permissions on the target root volume.

Request example¶

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

Request body¶

Parameter	Type	Required	Description
`filters`	array	Yes	Filter condition array, must contain a condition for `name` to `volume_id`.
`filters[].name`	string	Yes	Filter field name. `volume_id` must appear once. You may also pass `parent_id`, `file_name`, or `file_ext`.
`filters[].values`	array[string]	Yes	Filter value. `volume_id` must be a single positive integer. `parent_id` is the `id` of the parent `file_type=folder` entry.
`filters[].fuzzy`	boolean	No	Whether to use fuzzy matching when `name` is `file_name`.
`page`	integer	No	Page number.
`page_size`	integer	No	Number of items per page.
`order`	string	No	Sort direction: `asc` or `desc`.
`order_by`	string	No	Sorting field.

In this document, [] after a type means an array; for example, string[] is an array of strings. In field paths, [] means each item in an array; for example, filters[].name is the name field of each item in filters.

Omitting volume_id and sending only parent_id returns 400. To open the layer that the console labels “Open folder”, keep the original volume_id and add parent_id set to that folder entry’s id.

Successful response¶

Returns 200 and the file list on success. The caller needs read permissions on the target root volume.

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

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.total`	integer	The total number of entries matching the filter criteria.
`data.list`	array	List of file and folder entries.
`data.list[].id`	string	Entry ID.
`data.list[].name`	string	Entry name.
`data.list[].file_type`	string	Entry type: `file` or `folder`. `folder` is the “folder” tag in the console file list.
`data.list[].workflow_role`	string	Workflow product role; workflow output is `output`, other entries are empty strings.
`data.list[].file_ext`	string	File extension.
`data.list[].origin_file_name`	string	Original file name; returned when applicable.
`data.list[].origin_file_ext`	string	Original file extension; returned when applicable.
`data.list[].size`	integer	File size in bytes.
`data.list[].parent_id`	string	Parent ID.
`data.list[].volume_id`	string	The volume ID to which it belongs.
`data.list[].volume_name`	string	The name of the volume to which it belongs.
`data.list[].volume_reserved`	boolean	Whether the volume it belongs to is a reserved volume.
`data.list[].created_at`	string	Creation time, in RFC 3339 format.
`data.list[].created_by`	string	Creator ID.
`data.list[].ref_file_id`	string	The associated source file ID; returned when applicable.
`data.list[].parsed_file_id`	string	The file ID of the downloadable analysis product; returned when applicable.
`data.list[].ref_workflow_id`	string	Association workflow ID; returned when applicable.

Error response¶

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

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	The unique positive integer `volume_id` filter was not passed in.	Keep only one `volume_id` in `filters`.
`403`	`ErrForbidden`	The current identity does not have read permissions on the target root volume.	Check workspace and volume authorization.
`404`	`ErrNotFound`	The target volume does not exist.	Check `volume_id`.
`500`	`ErrServer`	The service cannot read the file list.	Record the request time and error message and try again; if it continues to fail, contact support.

Follow-up operations¶

Use data.list[].id to Query file details. When file_type is folder, call this API again with the current volume_id and that entry’s id as parent_id. That request matches the console “Open folder” action.

Last updated on Sep 3, 2026