文件管理

查询文件列表

查询业务空间下的文件列表，支持按类目、文件名和文件 ID 过滤

POST

/api/v1/connector/dash/listFile

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/connector/dash/listFile" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryId": "cate_abc123"
  }'

{
  "code": "Success",
  "message": "",
  "messageUnmodified": false,
  "requestId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "hasNext": false,
    "maxResult": 20,
    "totalCount": 1,
    "maxId": 338031,
    "fileList": [
      {
        "fileId": "file_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxx",
        "status": "PARSE_SUCCESS",
        "fileName": "a.md",
        "fileType": "md",
        "parser": "DASHSCOPE_DOCMIND",
        "sizeBytes": 21,
        "uploadTime": "2026-04-01 16:03:45",
        "category": "cate_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxx",
        "autoId": 338031,
        "parseErrorMessage": ""
      }
    ]
  },
  "status": 200
}

分页参数名为 maxResult（单数），传入 maxResults（复数）会被静默忽略，按默认 20 返回。

fileName 不含扩展名，如文件 a.md 应传 a，按精确匹配过滤。
fileIds 最多 20 个，用于批量查询指定文件。
响应中 parseErrorMessage 在解析失败时非空。

拿到 fileId 后，可在查询文件详情查看完整字段，或调用批量更新文件标签修改标签。

Authorizations

string

header

required

DashScope API Key，在控制台 API Key 页面（https://agent.console.aliyun.com/settings/apikey）获取。

Body

application/json

string

required

类目 ID，通过 listCategory 获取。

string

文件名（不含后缀），按精确匹配过滤。传入时需去掉扩展名，如文件 a.md 应传 a。

string[]

文件 ID 列表，最多 20 个，用于批量查询指定文件。

Required range:items <= 20

string

分页游标，首次查询不传；翻页时传入上一页响应返回的 nextToken 值。

integer

default20

每页返回的文件数量，默认 20。注意参数名为 maxResult（单数），传入 maxResults（复数）会被静默忽略。

Response

200-application/json

string

响应码，成功时为 Success。

integer

HTTP 状态码。

string

请求唯一标识，排查问题时请提供此 ID。

object

Show child attributes

object[]

文件列表。

Show child attributes

string

文件 ID。

string

文件名。

string

文件类型，如 pdf、md、docx。

string

所属类目 ID。

string

文件状态，如 PARSE_SUCCESS、PARSING、FAIL。

integer

文件大小（字节）。

string

解析方式，如 DASHSCOPE_DOCMIND、DOCUMENT_PARSE_LLM。

string

上传时间。

string

解析失败时的错误信息，成功时为空。

integer

自增 ID。

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/connector/dash/listFile" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryId": "cate_abc123"
  }'

{
  "code": "Success",
  "message": "",
  "messageUnmodified": false,
  "requestId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "hasNext": false,
    "maxResult": 20,
    "totalCount": 1,
    "maxId": 338031,
    "fileList": [
      {
        "fileId": "file_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxx",
        "status": "PARSE_SUCCESS",
        "fileName": "a.md",
        "fileType": "md",
        "parser": "DASHSCOPE_DOCMIND",
        "sizeBytes": 21,
        "uploadTime": "2026-04-01 16:03:45",
        "category": "cate_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxx",
        "autoId": 338031,
        "parseErrorMessage": ""
      }
    ]
  },
  "status": 200
}