List Files

POST/web/v1/files/query/listJWT + Turnstile

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

Authentication

Auth Chain: WEB Chain — requires Authorization: Bearer <jwt> and Turnstile token. These headers are injected by the system (frontend does nothing): X-PORTAL-ACCESS-CODE (Nginx), X-Request-Id (Gateway)

Request Parameters

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

Success Response

Success200

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

Unauthorized401

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

Bad Request400

{
  "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.