Skip to main content
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

This method directly calls the endpoint and returns the fileId and fileURL in the response.
MethodPOST
Endpointhttps://{host}/api/public/files
Content Typeapplication/json
AuthorizationX-api-key - The API key used for authentication.

​
Path Parameters

PARAMETERDESCRIPTIONTYPEREQUIRED/OPTIONAL
hostThe environment URL. For example, https://agent-platform.domain.ai/.StringRequired

​
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

PARAMETERDESCRIPTIONTYPEREQUIRED/OPTIONAL
fileThe file being uploaded.FileRequired
fileContextThe context of the file (for example, bulkImport).StringRequired

​
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

PARAMETERDESCRIPTIONTYPE
urlThe URL to access the uploaded file.String
fileIdUnique identifier for the uploaded fileString

​
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.
MethodPOST
Endpointhttp://{host}/api/public/files/session/start
Content Typeapplication/json
AuthorizationX-api-key - The API key used for authentication.

​
Path Parameters

PARAMETERDESCRIPTIONTYPEREQUIRED/OPTIONAL
hostThe environment URL. For example, https://agent-platform.domain.aiStringRequired

​
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

PARAMETERDESCRIPTIONTYPEREQUIRED/OPTIONAL
fileContextThe context of the file (for example, bulkImport).StringRequired
totalChunksThe total number of chunks created for the file upload.NumberRequired
fileExtensionThe file extension based on the file type.StringRequired
fileNameThe file name.StringRequired
fileSizeThe size of the file.NumberRequired

​
Sample Response

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

​
Response Parameters

PARAMETERDESCRIPTIONTYPE
sessionIdThe file upload session id.String
expirationDateThe 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.
MethodPOST
Endpointhttps://{host}/api/public/files/session/{sessionId}
Content Typeapplication/json
AuthorizationX-api-key - The API key used for authentication.

​
Path Parameters

PARAMETERDESCRIPTIONTYPEREQUIRED/OPTIONAL
hostThe environment URL. For example, https://agent-platform.domain.aiStringRequired
sessionIdThe file upload session id fetched from the Start Session API.StringRequired

​
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

PARAMETERDESCRIPTIONTYPEREQUIRED/OPTIONAL
fileThe file being uploaded.FileRequired
chunkNumberThe uploaded chunk number.NumberRequired

​
Sample Response

{
   "chunkNumber": "0",
   "sessionId": "14xxxxxd-xxx4-4xxf-axx1-69xxxxxxxxx8"
}

​
Response Parameters

PARAMETERDESCRIPTIONTYPE
chunkNumberThe uploaded chunk number.Number
sessionIdThe 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.
MethodPOST
Endpointhttps://{host}/api/public/files/session/{sessionid}/complete
Content Typeapplication/json
AuthorizationX-api-key - The API key used for authentication.

​
Path Parameters

PARAMETERDESCRIPTIONTYPEREQUIRED/OPTIONAL
hostThe environment URL. For example, https://agent-pxxxxxxxm.kxxe.aiStringRequired
sessionIDThe file upload session ID.StringRequired

​
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

PARAMETERDESCRIPTIONTYPE
urlThe uploaded file’s URL.String
fileIdThe file ID of the uploaded file.String