File Upload API

Back to API List

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.

The following file upload modes are supported:

• 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: 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

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

{
"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.
2. Upload in chunks, and
3. Merge the chunks to 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

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

{
   "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 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

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

{
   "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 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

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

{
"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