Presigned File Upload Mode
File Integration Upload Files
There are two places where file uploads are required on MaiAgent:
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 (like S3) without going through the server. In this mode, the server only generates time-sensitive 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 before being uploaded to cloud storage.
Presigned Mode: Files are uploaded directly from client to cloud, avoiding server file processing overhead.
Performance and Cost
Traditional mode can lead to high 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
Below describes how to complete the Presigned upload process using MaiAgent's provided API. For the Knowledge Base scenario, you need all 3 steps (Step 1 → 2 → 3). For message attachments, only Step 1 → 2 are needed.
1. Get Presigned URL
Endpoint
POST https://api.maiagent.ai/api/v1/upload-presigned-url/
Description
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 upload file
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 match actual binary size exactly, 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). The fields object in the response **includes the **x-amz-security-token field. When uploading in Step 2, you must pass every single fields entry (including x-amz-security-token) — missing any will cause S3 to reject the request.
Presigned URLs expire after ~1 hour — use them immediately after obtaining.
2. Upload File to Cloud Storage
Description
Use the url and fields obtained from the previous step to upload files directly to cloud storage. Every entry in the fields object must be sent (including x-amz-security-token). Do not hardcode the field list — dynamic packing avoids missing newly-added fields in the future.
On success, S3 returns HTTP 204 No Content (empty body).
Example Request (curl, with STS token)
Example Request (Python, dynamic packing, recommended)
3. Register the File to a Knowledge Base (KB scenario only)
Endpoint
POST https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/
Description
After Step 2, the file binary is in S3 but not yet associated with a Knowledge Base. You need to call this API to register the upload as a KnowledgeBaseFile, which triggers parsing, chunking, and indexing.
The file field must be the fields.key returned in Step 1 (MaiAgent's internal S3 relative path) — not an arbitrary external URL. If you have an external URL (e.g., a partner's download link), first GET to download the file, then follow Step 1 → 2 → 3.
Path Parameters
knowledgeBasePk
string
The unique identifier (UUID) of the knowledge base
Request Parameters
files
array
Yes
List of files to create; supports batch creation
files[].filename
string
Yes
Original file name
files[].file
string
Yes
The fields.key from Step 1 response (relative path, not URL)
files[].parser
string
No
Parser UUID; uses KB default if omitted
files[].labels
array
No
File labels (array of {id, name} objects)
files[].rawUserDefineMetadata
object
No
User-defined metadata
Example Request
Example Response
File Status (status)
initial
Just created, waiting to be processed
processing
Parsing, chunking, and indexing in progress
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 x-amz-security-token, or you've hardcoded an expired access key / outdated S3 endpoint. Always use the url and fields returned by Step 1, and pass the entire fields object as-is to Step 2.
Q: S3 returns Policy Condition failed
A: Usually the fileSize in Step 1 doesn't match the actual binary size. Recalculate the actual file size and re-run Step 1.
Q: Step 3 returns 400 complaining about the file field
A: The file field must be the fields.key returned by Step 1 (e.g., media/chatbots/chatbot-file/xxx.pdf), not Step 3's response full URL, nor an arbitrary external URL.
Q: I already have an external URL (e.g., a partner's download link) — can I pass it directly to Step 3?
A: No. Step 3's file field is a MaiAgent S3 relative key. First GET to download the file from that external URL, then go through Step 1 → 2 → 3.
Q: File stays in status: processing after Step 3
A: Parsing time depends on file size and type — large files may take several minutes. Poll with GET /api/v1/knowledge-bases/{KB_ID}/files/{file_id}/ to check status; only files with status: done are retrievable by AI assistants.
Last updated
Was this helpful?