Upload File

POST/web/v1/files/command/uploadJWT + Turnstile

Uploads a file to the platform storage. The file is stored in an object storage bucket and a metadata record is created for tracking. Requires both JWT authentication and Turnstile verification.

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
file	MultipartFile	Yes	form-data	The file to upload
bucket	string	No	query	Target storage bucket. If omitted, the default bucket is used.
remark	string	No	query	Optional remark or description for the file
workspaceBizId	string	No	query	Workspace business ID to associate the file with

Success Response

Created201

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "bizId": "file_abc123",
    "bucket": "default",
    "objectKey": "uploads/2026/03/21/file_abc123.pdf",
    "originalFilename": "invoice.pdf",
    "fileSize": 102400,
    "contentType": "application/pdf",
    "fileCategory": "DOCUMENT",
    "accessUrl": "https://storage.example.com/uploads/2026/03/21/file_abc123.pdf",
    "etag": "d41d8cd98f00b204e9800998ecf8427e"
  }
}

Error Responses

Unauthorized401

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

Bad Request400

{
  "success": false,
  "code": "4000",
  "message": "File is required"
}

Notes

• The request must use multipart/form-data content type.
• File size limits and allowed content types are configured server-side.
• The etag can be used for integrity verification.