> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Upload API

[Back to API List](https://koreai.mintlify.site/agent-platform/v1/apis.md)

The API uploads a file to the server for seamless usage in multi modal nodes and across the Platform. The API returns a unique `file URL` and `file ID` for further action on the file.

We support the following file extensions:

* M4a
* Mp3
* Webm
* Mp4
* Mpga
* Wav
* Mpeg
* PNG (.png)
* JPEG (.jpeg and .jpg)
* WEBP (.webp)
* GIF (.gif)

To use the API, [create an API key](https://koreai.mintlify.site/agent-platform/v1/apis.md#how-to-create-the-api-key).

The following file upload modes are supported:

* [Mode 1 - Upload a single file as is](#mode-1-upload-a-single-file-as-is): Use this mode if your file is smaller than 25 MB.
* [Mode 2 - Upload a file in chunks](#mode-2-upload-a-file-in-chunks): Use this mode if your file is larger than 25 MB. Ensure you start the session for chunk uploads before proceeding.

## Mode 1: Upload a Single File As Is

This method directly calls the endpoint and returns the `fileId` and `fileURL` in the response.

| Method | POST |
| :- | :- |
| Endpoint | `https://{host}/api/public/files` |
| Content Type | application/json |
| Authorization | `X-api-key` - The API key used for authentication. |

### Path Parameters

| PARAMETER | DESCRIPTION | TYPE | REQUIRED/OPTIONAL |
| :- | :- | :- | :- |
| host | The environment URL. For example, `https://agent-platform.domain.ai/`. | String | Required |

### Sample Request

```js theme={null}
curl --location 'https://{host}/api/public/files' 
--header 'x-api-key: xxxxx' 
--form 'file=@"postman-cloud:///1efxxxxe-bxx9-4xx0-bxx3-14xxxxxxxxx9"' 
--form 'fileContext="bulkImport"'
```

### Body Parameters

| PARAMETER | DESCRIPTION | TYPE | REQUIRED/OPTIONAL |
| :- | :- | :- | :- |
| file | The file being uploaded. | File | Required |
| fileContext | The context of the file (for example, `bulkImport`). | String | Required |

### Sample Response

```js theme={null}
{
"url": "http://{host}/api/getMediaStream/orgFiles/f-e1xxxxx3-4xxc-5xx6-bxx2-cxxxxxxxxxx7.wav?e=173xxxxx36&n=13xxxx7188&del=false&s=IkJyODZMM3V6K1I3UkYraERHSHVuOWY1M08xYjJoN3NLMmVTR0FMbWtiK2M9Ig%24%24&fileName=sample4.wav",
"fileId":"657xxxxxxxxxxxxxxxxxxxx6"
}
```

### Response Parameters

| PARAMETER | DESCRIPTION | TYPE |
| :- | :- | :- |
| url | The URL to access the uploaded file. | String |
| fileId | Unique identifier for the uploaded file | String |

## Mode 2: Upload a File in Chunks

This method requires the following three APIs to upload a large file:

1. [Start the file upload session](#start-session-api).
2. [Upload in chunks](#chunk-upload-api), and
3. [Merge the chunks to complete the process](#complete-the-process).

### Start Session API

This API starts the upload process, returning a `session ID`. The file is split into chunks linked to this ID, which are then merged and uploaded through other APIs.

| Method | POST |
| :- | :- |
| Endpoint | `http://{host}/api/public/files/session/start` |
| Content Type | application/json |
| Authorization | `X-api-key` - The API key used for authentication. |

#### Path Parameters

| PARAMETER | DESCRIPTION | TYPE | REQUIRED/OPTIONAL |
| :- | :- | :- | :- |
| host | The environment URL. For example, `https://agent-platform.domain.ai` | String | Required |

#### Sample Request

```js theme={null}
curl --location 'https://{host}/api/public/files/session/start' 
--header 'x-api-key: kg-b9xxxxxc-cxxf-5xxf-8xxe-6xxxxxxxxxx8-3xxxxx2a-exxa-4xx8-8xx5-exxxx1axxxxxd' 
--header 'Content-Type: application/json' 
--data '{
    "fileContext": "bulkImport",
    "totalChunks": 1,
    "fileExtension": "jpg",
    "fileName": "Rent.jpg",
    "fileSize": 291
}'
```

#### Body Parameters

| PARAMETER | DESCRIPTION | TYPE | REQUIRED/OPTIONAL |
| :- | :- | :- | :- |
| fileContext | The context of the file (for example, `bulkImport`). | String | Required |
| totalChunks | The total number of chunks created for the file upload. | Number | Required |
| fileExtension | The file extension based on the file type. | String | Required |
| fileName | The file name. | String | Required |
| fileSize | The size of the file. | Number | Required |

#### Sample Response

```js theme={null}
{
   "sessionId": "14xxxxxd-0xx4-4xxf-axx1-69xxxxxxxxx8",
   "expirationDate": "2025-02-06T16:01:44.285Z"
}
```

#### Response Parameters

| PARAMETER | DESCRIPTION | TYPE |
| :- | :- | :- |
| sessionId | The file upload `session id`. | String |
| expirationDate | The date and time of the session expiration. | Date |

### Chunk Upload API

The API uploads the file in multiple chunks. The `session ID` from the [Start Session](#start-session-api) API must be used in this step.

| Method | POST |
| :- | :- |
| Endpoint | `https://{host}/api/public/files/session/{sessionId}` |
| Content Type | application/json |
| Authorization | `X-api-key` - The API key used for authentication. |

#### Path Parameters

| PARAMETER | DESCRIPTION | TYPE | REQUIRED/OPTIONAL |
| :- | :- | :- | :- |
| host | The environment URL. For example, `https://agent-platform.domain.ai` | String | Required |
| sessionId | The file upload `session id` fetched from the Start Session API. | String | Required |

#### Sample Request

```js theme={null}
curl --location 'https://{host}/api/public/files/session/14xxxxxd-0xx4-4xxf-axx1-69xxxxxxxxx8' 
--header 'x-api-key: {{apikey}}' 
--header 'Content-Type: application/json' 
--form 'file=@"postman-cloud:///1exxxxxc-9xxd-4xx0-8xxa-3xxxxxxxxxxa"' 
--form 'chunkNumber="0"'
```

#### Body Parameters

| PARAMETER | DESCRIPTION | TYPE | REQUIRED/OPTIONAL |
| :- | :- | :- | :- |
| file | The file being uploaded. | File | Required |
| chunkNumber | The uploaded chunk number. | Number | Required |

#### Sample Response

```js theme={null}
{
   "chunkNumber": "0",
   "sessionId": "14xxxxxd-xxx4-4xxf-axx1-69xxxxxxxxx8"
}
```

#### Response Parameters

| PARAMETER | DESCRIPTION | TYPE |
| :- | :- | :- |
| chunkNumber | The uploaded chunk number. | Number |
| sessionId | The file upload `session id`. | String |

### Complete The Process

This API merges the uploaded chunks and finalizes the process using the `session Id` from the [Start Session](#start-session-api) API. It returns the `file URL` and `file ID`. Missing chunk numbers are identified after the merge.

| Method | POST |
| :- | :- |
| Endpoint | `https://{host}/api/public/files/session/{sessionid}/complete` |
| Content Type | application/json |
| Authorization | `X-api-key` - The API key used for authentication. |

#### Path Parameters

| PARAMETER | DESCRIPTION | TYPE | REQUIRED/OPTIONAL |
| :- | :- | :- | :- |
| host | The environment URL. For example, `https://agent-platform.kore.ai` | String | Required |
| sessionID | The file upload `session ID`. | String | Required |

#### Sample Request

```js theme={null}
curl --location --request POST 'https://localhost/api/public/files/session/6exxxxx9-4xx7-4xx1-bxx9-ef2xxxxxxx78/complete' 
--header 'x-api-key: kg-a3xxxxxe-0xx6-5xx1-axxc-d4xxxxxxxxx0-a8xxxxxc-bxx4-4xxe-axxd-dxxxxxxxxxxf'
```

#### Body Parameters

No parameters are passed.

#### Sample Response

```js theme={null}
{
"url": "http://{host}/api/getMediaStream/orgFiles/f-e1xxxxx3-4xxc-5xx6-bxx2-c8xxxxxxxxx7.wav?e=1736922836&n=1357527188&del=false&s=IkJyODZMM3V6K1I3UkYraERHSHVuOWY1M08xYjJoN3NLMmVTR0FMbWtiK2M9Ig%24%24&fileName=sample4.wav",
    "fileId": "657xxxxxxxxxxxxxxxxxxxx6"
}
```

#### Response Parameters

| PARAMETER | DESCRIPTION | TYPE |
| :- | :- | :- |
| url | The uploaded file’s URL. | String |
| fileId | The file ID of the uploaded file. | String |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.