Skip to content

File Upload API

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

The following file extensions are currently supported:

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

Where can I find the API key?

To use the API, you will need an API key. Learn more.

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.

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 (e.g., 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 (e.g., 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-pxxxxxxxm.kxxe.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