Presigned File Upload Mode
File Integration Upload Files
There are currently two places on MaiAgent that require file uploads:
Knowledge Base Document Upload
Message Attachment Upload
Presigned Upload Mode
MaiAgent supports Presigned Upload Mode, which allows clients to upload files directly to cloud storage (such as S3) without going through the server as a relay. In this mode, the server is only responsible for generating time-limited and secure Presigned URLs, and clients use these URLs to upload files directly.
Differences from Traditional Upload Mode:
Data Flow
Traditional Mode: Files must pass through the server, which then uploads them to cloud storage.
Presigned Mode: Files are uploaded directly from the client to cloud storage, avoiding the server's file processing overhead.
Performance and Cost
Traditional mode can lead to excessive server resource consumption and increased data transfer costs.
Presigned mode reduces server load, improves performance, and lowers transfer costs.
Security
Presigned URLs include signatures and expiration times, ensuring upload requests are limited to authorized users within specified timeframes.
This mode is particularly suitable for large files or high-frequency upload scenarios, improving efficiency while maintaining high security.
Presigned Upload Flow Diagram
Traditional Upload Flow Diagram
Presigned File Upload
The following describes how to complete the Presigned file upload process using MaiAgent's API. Knowledge base scenarios require all 3 steps (Step 1 → 2 → 3), while message attachment scenarios only require Step 1 → 2.
1. Get Presigned URL
Endpoint
POST https://api.maiagent.ai/api/v1/upload-presigned-url/
Description
The client sends a request to the server to obtain a Presigned URL for directly uploading files to cloud storage.
Request Parameters
filename
string
Yes
Name of the file to upload
modelName
string
Yes
Module name for categorizing file usage
Use chatbot-file for knowledge base
Use attachment for message attachments
fieldName
string
Yes
File field name for identifying file purpose
fileSize
integer
Yes
File size (in bytes); must exactly match the actual binary size, otherwise Step 2 will be rejected by S3
Example Request
Example Response
The production environment uses AWS STS short-lived credentials (x-amz-credential starts with ASIA), and the response fields object will include the x-amz-security-token field. When uploading in Step 2, you must include every single fields field (including x-amz-security-token) without omission — missing any field will cause S3 to reject the request.
The Presigned URL is valid for approximately 1 hour. Use it as soon as possible after obtaining it.
2. Upload File to Cloud Storage
Description
Use the url and fields obtained from the previous step to upload the file directly to cloud storage. Every field in the fields object must be included (including x-amz-security-token); do not hardcode the field list — dynamically assembling ensures no fields are missed if AWS adds new ones in the future.
A successful S3 upload returns HTTP 204 No Content (empty body).
Example Request (curl, with STS token)
Example Request (Python, dynamic assembly, recommended approach)
3. Register File to Knowledge Base (Knowledge Base Scenario Only)
Endpoint
POST https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/
Description
After Step 2 is complete, the file binary is already in S3, but it has not yet been added to the knowledge base. You need to call this API to register the upload result as a KnowledgeBaseFile, and only then will the system begin parsing, chunking, and building the index.
The file field must contain the fields.key from the Step 1 response (the MaiAgent S3 internal relative path), not an arbitrary external URL. If you have an external URL (e.g., a download link from a partner system), first download the file using GET, then follow Step 1 → 2 → 3.
Path Parameters
knowledgeBasePk
string
Unique identifier (UUID) of the knowledge base
Request Parameters
files
array
Yes
List of files to create; multiple files can be batch-created at once
files[].filename
string
Yes
Original filename
files[].file
string
Yes
fields.key from the Step 1 response (relative path, not a URL)
files[].parser
string
No
UUID of the specified parser; uses the knowledge base default if omitted
files[].labels
array
No
File labels ({id, name} object array)
files[].rawUserDefineMetadata
object
No
User-defined metadata
Example Request
Example Response
File Status (status)
initial
Just created, awaiting processing
processing
Currently parsing, chunking, and building index
done
Processing complete, available for retrieval
failed
Processing failed
Common Errors and Troubleshooting
Q: S3 returns The AWS Access Key Id you provided does not exist in our records
A: Step 2 is missing the x-amz-security-token, or you hardcoded an expired access key / S3 endpoint. Always use the url and fields returned in real-time from Step 1, and pass the entire fields object as-is to Step 2.
Q: S3 returns Policy Condition failed
A: This is usually because the fileSize in Step 1 does not match the actual binary size. Recalculate the actual file size and re-run Step 1.
Q: Step 3 returns 400, saying the file field is invalid
A: The file field must contain the fields.key from the Step 1 response (e.g., media/chatbots/chatbot-file/xxx.pdf), not the full URL from the Step 3 response, nor any arbitrary external URL.
Q: I already have an external URL (e.g., a download link from a partner system). Can I pass it directly to Step 3?
A: No. The file field in Step 3 is a relative key within MaiAgent's own S3. First download the file from that external URL using GET, then follow Step 1 → 2 → 3.
Q: After Step 3, the file stays in status: processing
A: Parsing time depends on file size and type; large files may take several minutes. You can poll the status using GET /api/v1/knowledge-bases/{KB_ID}/files/{file_id}/ and wait until it reaches done before the AI assistant can retrieve it.
Last updated
Was this helpful?