Upload File

POST/web/v1/files/command/upload JWT + 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.

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

Success Response

Created 201

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

Unauthorized 401

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

Bad Request 400

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