Add File

Add File API allows you to upload a file as a project asset and optionally link it with an AI Agent.

This endpoint is used when you want to upload documents or knowledge files. If chatbot_id is provided, the uploaded file will be linked with the AI Agent as a knowledge asset. If chatbot_id is not provided, the file will only be uploaded and the API will return the uploaded file asset_url.

Endpoint

Request Content Type

Path Parameters

Name	Type	Required	Description
`projectId`	integer	Yes	Unique identifier of the project where the file should be uploaded.

Body Parameters

Name	Type	Required	Description
`chatbot_id`	string	No	Unique chatbot identifier. If provided, the uploaded file will be linked with this agent. If not provided, the file will only be uploaded.
`file`	file	Yes	File to upload as a project asset. Maximum allowed file size is 10 MB.
`metadata`	string	No	Optional metadata for the uploaded file. This can be a JSON string containing source, category, tags, or other custom details.

File Upload Limitations

Rule	Value
Maximum file size	`10 MB`
Supported file types	`PDF`, `DOCX`, `DOC`, `XLS`, `XLSX`, `TXT`, `HTML`, `MD`, `Markdown`, `JSON`

Request Example: Upload File Only

Use this request when you only want to upload a file and get the uploaded file URL.

Request Example: Upload File and Link With Agent

Use this request when you want to upload a file and link it with a agent.

Success Response: File Uploaded Only

Returned when chatbot_id is not provided.

{
  "message": "File uploaded successfully",
  "data": {
    "status": "Uploaded",
    "asset_url": "https://chatbot-ai-agent.s3.eu-west-1.amazonaws.com/projects/123/sample.pdf"
  }
}

Success Response: File Uploaded and Linked With Agent

Returned when chatbot_id is provided.

{
  "message": "Chatbot asset linkage initiated.",
  "data": {
    "linkage_id": 6548,
    "chatbot_id": "DKDvwn...",
    "asset_id": 5782,
    "status": "Processing"
  }
}

Response Fields

Field	Type	Description
`message`	string	Human-readable response message.
`data`	object	Response data object.
`data.linkage_id`	integer	Unique identifier of the link created between the chatbot and uploaded file. Returned only when `chatbot_id` is provided.
`data.chatbot_id`	string	Unique chatbot identifier linked with the uploaded file. Returned only when `chatbot_id` is provided.
`data.asset_id`	integer	Unique identifier of the uploaded file asset. Returned when the file is linked with a chatbot.
`data.status`	string	Current upload or linking status. Example values: `Uploaded`, `Processing`, `Linked`, `Failed`.
`data.asset_url`	string	URL of the uploaded file asset. Returned when the file is uploaded without chatbot linking.

Error Responses

400 Bad Request

Returned when the request is invalid, the file is missing, the file size exceeds the limit, or the uploaded file type is not supported.

{
  "message": "Bad Request",
  "error": {
    "code": "BAD_REQUEST",
    "detail": "File is required, file size must not exceed 10 MB, and file type must be one of PDF, DOCX, DOC, XLS, XLSX, TXT, HTML, MD, Markdown, or JSON."
  }
}

401 Unauthorized

Returned when the request does not include a valid bearer token.

{
  "message": "Unauthorized",
  "error": {
    "code": "UNAUTHORIZED",
    "detail": "Authentication token is missing or invalid."
  }
}

403 Forbidden

Returned when the authenticated user does not have permission to upload files to the specified project or chatbot.

{
  "message": "Forbidden",
  "error": {
    "code": "FORBIDDEN",
    "detail": "You do not have permission to upload or link files for this project."
  }
}

404 Not Found

Returned when the project or chatbot does not exist.

{
  "message": "Not Found",
  "error": {
    "code": "CHATBOT_NOT_FOUND",
    "detail": "Project or chatbot not found."
  }
}

500 Internal Server Error

Returned when an unexpected error occurs while uploading or linking the file.

{
  "message": "Internal Server Error",
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "detail": "Something went wrong. Please try again later."
  }
}

Notes

The request must be sent as multipart/form-data.

The file field is required.

Maximum file size is 10 MB.

Supported file types are: PDF, DOCX, DOC, XLS, XLSX, TXT, HTML, MD, Markdown, and JSON.

The chatbot_id field is optional.

If chatbot_id is provided, the uploaded file will be linked with the chatbot and processed as a knowledge asset.

If chatbot_id is not provided, the file will only be uploaded and the API will return asset_url.

File processing may take some time before the chatbot can use the uploaded knowledge.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Endpoint#

Request Content Type#

Path Parameters#

Body Parameters#

File Upload Limitations#

Request Example: Upload File Only#

Request Example: Upload File and Link With Agent#

Success Response: File Uploaded Only#

Success Response: File Uploaded and Linked With Agent#

Response Fields#

Error Responses#

400 Bad Request#

401 Unauthorized#

403 Forbidden#

404 Not Found#

500 Internal Server Error#

Notes#

Request

Responses