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

<Badge icon="arrow-left" color="gray">[Back to API List](/agent-platform/v1/apis)</Badge>

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](/agent-platform/v1/apis#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 |