List Files

POST/web/v1/files/query/list JWT + Turnstile

Returns a paginated list of files matching the specified filter criteria. Results are sorted by creation time in descending order by default.

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token
X-Workspace-Id		Target workspace ID

Request Parameters

Name	Type	Required	In	Description
institutionBizId	string	Required	body	Institution business ID to scope the query
workspaceBizId	string	Optional	body	Optional workspace business ID filter
fileCategory	integer	Optional	body	File category code filter
fileStatus	integer	Optional	body	File status code filter
page	integer	Optional	query	Page number (zero-based). Default: `0`
size	integer	Optional	query	Page size. Default: `20`
sort	string	Optional	query	Sort field and direction. Default: `createdAt,desc`

Success Response

Success 200

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "content": [
      {
        "bizId": "file_abc123",
        "bucket": "default",
        "objectKey": "uploads/2026/03/21/file_abc123.pdf",
        "originalFilename": "invoice.pdf",
        "fileSize": 102400,
        "contentType": "application/pdf",
        "fileCategory": "DOCUMENT",
        "fileStatus": "ACTIVE",
        "etag": "d41d8cd98f00b204e9800998ecf8427e",
        "remark": "Monthly invoice",
        "createdAt": "2026-03-21T00:00:00Z",
        "createdBy": "acc_user123"
      }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "size": 20,
    "number": 0
  }
}

Error Responses

Unauthorized 401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

Bad Request 400

{
  "success": false,
  "code": "4000",
  "message": "Institution business ID is required"
}

Notes

• The institutionBizId is required and scopes all results to a single institution.
• Uses POST method to support complex filter criteria in the request body.