# Presigned File Upload Mode

There are two places where file uploads are required on MaiAgent:

1. Knowledge Base Document Upload
2. 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:

1. **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.
2. **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.
3. **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

{% @mermaid/diagram content="sequenceDiagram
participant Client as Client
participant Server as Sever
participant S3 as Storage(S3)

```
Note over Client,S3: Presigned Upload Flow

Client->>+Server: 1. Request Presigned URL
Note right of Client: POST /api/v1/presigned<br/>Include filename, type, size

Server->>Server: 2. Validate Request Parameters
Server->>Server: 3. Generate Presigned Parameters
Note right of Server: Set expiration, permissions, etc.
Server-->>-Client: 4. Return Presigned URL and Parameters

Client->>+S3: 5. Upload Using Presigned URL
Note right of Client: POST to Presigned URL<br/>Can monitor upload progress
S3-->>-Client: 6. Upload Complete Response

opt Upload Complete Notification
    Client->>+Server: 7. Notify Upload Complete
    Note right of Client: POST /api/v1/upload/complete
    Server->>Server: 8. Update Database Records
    Server-->>-Client: 9. Confirmation Response
end" %}
```

#### Traditional Upload Flow Diagram

{% @mermaid/diagram content="sequenceDiagram
participant Client as Client
participant Server as Server
participant S3 as Storage(S3)

```
Note over Client,S3: Traditional Upload Flow

Client->>+Server: 1. Upload File Request
Note right of Client: POST /api/v1/upload<br/>File content included in request

Server->>Server: 2. Validate File<br/>(size, type, format)
Server->>Server: 3. Store Temporary File

Server->>+S3: 4. Upload File to S3
Note right of Server: Use AWS SDK<br/>Upload temp file
S3-->>-Server: 5. Upload Success Response

Server->>Server: 6. Clean Up Temp File
Server-->>-Client: 7. Return Upload Result
Note left of Server: Return S3 file location" %}
```

***

#### Presigned File Upload

Below describes how to complete the Presigned upload process using MaiAgent's provided API.

#### 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**

| Parameter Name | Type      | Required | Description                                                                                                                                                         |
| -------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename`     | `string`  | Yes      | Name of the upload file                                                                                                                                             |
| `modelName`    | `string`  | Yes      | <p>Module name for categorizing file usage<br></p><p>Use <code>chatbot-file</code> for knowledge base</p><p>Use <code>attachment</code> for message attachments</p> |
| `fieldName`    | `string`  | Yes      | File field name for identifying file purpose                                                                                                                        |
| `fileSize`     | `integer` | Yes      | File size (in bytes)                                                                                                                                                |

**Example Request**

```bash
curl --location 'https://api.maiagent.ai/api/v1/upload-presigned-url/' \
--header 'Authorization: Api-Key ' \
--header 'Content-Type: application/json' \
--data '{
    "filename": "Products_example.xlsx",
    "modelName": "chatbot-file",
    "fieldName": "file",
    "fileSize": 5881
}'
```

**Example Response**

```json
{
    "url": "https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app",
    "fields": {
        "key": "media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx",
        "x-amz-algorithm": "AWS4-HMAC-SHA256",
        "x-amz-credential": "AKIATIVCN4X5JXWAP43M/20241129/ap-northeast-1/s3/aws4_request",
        "x-amz-date": "20241129T012318Z",
        "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMTEtMjlUMDI6MjM6MThaIiwgImNvbmRpdGlvbnMiOiBbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwMF0sIHsiYnVja2V0IjogIndoaXpjaGF0LW1lZGlhLXByb2QtZGphbmdvLnBsYXltYS5hcHAifSwgeyJrZXkiOiAibWVkaWEvY2hhdGJvdHMvY2hhdGJvdC1maWxlL2Q4M2M4OGFhLTM4NzQtNDlhNi1iMDFlLTE5NDhhZTQ4Yjc0Ny54bHN4In0sIHsieC1hbXotYWxnb3JpdGhtIjogIkFXUzQtSE1BQy1TSEEyNTYifSwgeyJ4LWFtei1jcmVkZW50aWFsIjogIkFLSUFUSVZDTjRYNUpYV0FQNDNNLzIwMjQxMTI5L2FwLW5vcnRoZWFzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LCB7IngtYW16LWRhdGUiOiAiMjAyNDExMjlUMDEyMzE4WiJ9XX0=",
        "x-amz-signature": "0254b3baa65c3a69eaeeccd0a3d027bc7952c1587cc96437c096eb1b76e1d692"
    }
}
```

***

#### 2. **Upload File to Cloud Storage**

**Description**

Use the `url` and `fields` obtained from the previous step to upload files directly to cloud storage.

**Example Request**

```bash
curl --location 'https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app' \
--form 'key="media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx"' \
--form 'x-amz-algorithm="AWS4-HMAC-SHA256"' \
--form 'x-amz-credential="AKIATIVCN4X5JXWAP43M/20241129/ap-northeast-1/s3/aws4_request"' \
--form 'x-amz-date="20241129T012318Z"' \
--form 'policy="eyJleHBpcmF0aW9uIjogIjIwMjQtMTEtMjlUMDI6MjM6MThaIiwgImNvbmRpdGlvbnMiOiBbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwMF0sIHsiYnVja2V0IjogIndoaXpjaGF0LW1lZGlhLXByb2QtZGphbmdvLnBsYXltYS5hcHAifSwgeyJrZXkiOiAibWVkaWEvY2hhdGJvdHMvY2hhdGJvdC1maWxlL2Q4M2M4OGFhLTM4NzQtNDlhNi1iMDFlLTE5NDhhZTQ4Yjc0Ny54bHN4In0sIHsieC1hbXotYWxnb3JpdGhtIjogIkFXUzQtSE1BQy1TSEEyNTYifSwgeyJ4LWFtei1jcmVkZW50aWFsIjogIkFLSUFUSVZDTjRYNUpYV0FQNDNNLzIwMjQxMTI5L2FwLW5vcnRoZWFzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LCB7IngtYW16LWRhdGUiOiAiMjAyNDExMjlUMDEyMzE4WiJ9XX0="' \
--form 'x-amz-signature="0254b3baa65c3a69eaeeccd0a3d027bc7952c1587cc96437c096eb1b76e1d692"' \
--form 'file=@"/Users/maiagent/Downloads/Products_example.png"'
```

***

##


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tech/maiagent-tech-en/api-integration/api_knowledge.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.