# 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"'
```

***

##