Files

You can use the API to download and upload binary files. The API supports three types of file uploads: chat files (with automatic expiration), project assets, and user/bot avatars.

File Upload Types

• Chat files: Files uploaded during conversations. These have automatic expiration (default: 30 days).

• Assets: Project assets that can be used across the platform. These have no expiration by default, but can be set via query parameter. Images automatically generate thumbnails.

• Avatars: User profile photos or bot avatars. These have no expiration and are stored in a fixed path structure.

Upload a project asset

POST https://api.tiledesk.com/v3/:project_id/files/assets

Uploads a file as a project asset. Assets have no expiration by default, but can be set via query parameter.

Path Parameters

Name	Type	Description
project_id	string	The Project Id is a unique code assigned to your project when you create it in Tiledesk.

Query Parameters

Name	Type	Description
expiration	number	Optional. Expiration time in seconds. If provided and greater than 0, the file will expire after this time.

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: admin
Content-Type	string	Use "multipart/form-data" value

Request Body

Name	Type	Description
file	binary	The binary file to upload. Must match allowed extensions for assets. Images will automatically generate thumbnails.

201 File uploaded successfully

{
  "message": "File uploaded successfully",
  "filename": "uploads/projects/5ebd890292befe0019054973/files/uuid/logo.png",
  "thumbnail": "uploads/projects/5ebd890292befe0019054973/files/uuid/thumbnails_200_200-logo.png"
}

400 Bad request - Invalid file or upload error

403 Forbidden - File extension not allowed or content verification failed

413 File too large

Example:

curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u [email protected]:password \
  -F [email protected] \
  https://api.tiledesk.com/v3/files/assets?expiration=86400

Upload a chat file

POST https://api.tiledesk.com/v3/:project_id/files/chat

Uploads a file for use in chat conversations. The file will automatically expire after a configured time (default: 30 days).

Path Parameters

Name	Type	Description
project_id	string	The Project Id is a unique code assigned to your project when you create it in Tiledesk.

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT.
Content-Type	string	Use "multipart/form-data" value

Request Body

Name	Type	Description
file	binary	The binary file to upload.

201 File uploaded successfully

{
  "message": "File uploaded successfully",
  "filename": "uploads/projects/5ebd890292befe0019054973/files/uuid/document.pdf"
}

400 Bad request - Invalid file or upload error

403 Forbidden - File extension not allowed or content verification failed

413 File too large

Example:

curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u [email protected]:password \
  -F [email protected] \
  https://api.tiledesk.com/v3/files/chat

Upload user profile photo or bot avatar

POST https://api.tiledesk.com/v3/:project_id/files/users/photo

Uploads a profile photo for a user or avatar for a bot. Only image files are allowed (.png, .jpg, .jpeg, .gif). The file is stored in a fixed path structure: uploads/users/{user_id|bot_id}/images/photo.jpg. Automatically generates a 200x200 thumbnail. Requires agent role or bot/subscription authentication.

Path Parameters

Name	Type	Description
project_id	string	The Project Id is a unique code assigned to your project when you create it in Tiledesk.

Query Parameters

Name	Type	Description
bot_id	string	Optional. If provided, uploads the avatar for the specified bot. The authenticated user must be an admin or owner of the bot's project.

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: agent
Content-Type	string	Use "multipart/form-data" value

Request Body

Name	Type	Description
file	binary	The image file to upload. Must be one of: .png, .jpg, .jpeg, .gif

201 Image uploaded successfully

{
  "message": "Image uploaded successfully",
  "filename": "uploads/users/5ebd890292befe0019054973/images/photo.jpg",
  "thumbnail": "uploads/users/5ebd890292befe0019054973/images/thumbnails_200_200-photo.jpg"
}

400 Bad request - No file uploaded or invalid file

401 Unauthorized - User doesn

403 Forbidden - Insufficient permissions or file extension not allowed

404 Chatbot not found

413 File too large

Example (user photo):

curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u [email protected]:password \
  -F [email protected] \
  https://api.tiledesk.com/v3/files/users/photo

Example (bot avatar):

curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u [email protected]:password \
  -F file=@bot_avatar.png \
  https://api.tiledesk.com/v3/files/users/photo?bot_id=65c5f3599faf2d04cd7da528

Get the binary file as stream by filename path

GET https://api.tiledesk.com/v3/files

Retrieves a file as a stream by its path. The file is returned with appropriate Content-Type headers. If the file is not found in the primary storage, the system automatically falls back to a secondary storage service.

Query Parameters

Name	Type	Description
path	string	The file path (URL encoded). Example: uploads/projects/5ebd890292befe0019054973/files/uuid/document.pdf
as_attachment	boolean	Optional. If set, the file will be returned with Content-Disposition header set to attachment, forcing download.

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT

200 File stream

<binary content>

404 File not found

500 Error getting file

Example:

curl -v -X GET \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/files?path=uploads%2Fprojects%2F5ebd890292befe0019054973%2Ffiles%2Fuuid%2Fdocument.pdf"

Example (as attachment):

curl -v -X GET \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/files?path=uploads%2Fprojects%2F5ebd890292befe0019054973%2Ffiles%2Fuuid%2Fdocument.pdf&as_attachment=true"

Download the binary file by filename path

GET https://api.tiledesk.com/v3/files/download

Downloads a file by its path. The file is returned with Content-Disposition header set to attachment, forcing download with the original filename.

Query Parameters

Name	Type	Description
path	string	The file path (URL encoded). Example: uploads/projects/5ebd890292befe0019054973/files/uuid/document.pdf

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT

200 File download

<binary content>

404 File not found

500 Error getting file

Example:

curl -v -X GET \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/files/download?path=uploads%2Fprojects%2F5ebd890292befe0019054973%2Ffiles%2Fuuid%2Fdocument.pdf"

Delete a file

DELETE https://api.tiledesk.com/v3/files

Deletes a file by its path. If the file is an image, the associated thumbnail (if exists) will also be deleted automatically. The system checks both primary and fallback storage services.

Query Parameters

Name	Type	Description
path	string	The file path (URL encoded). Example: uploads/users/65c5f3599faf2d04cd7da528/images/photo.jpg or uploads/projects/65c5f3599faf2d04cd7da528/files/uuid/logo.png

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT

200 File deleted successfully

{
  "message": "File deleted successfully",
  "filename": "uploads/users/65c5f3599faf2d04cd7da528/images/photo.jpg"
}

400 Bad request - Path parameter missing or invalid

404 File not found

500 Error deleting file

Example (delete user photo):

curl -v -X DELETE \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/files?path=uploads%2Fusers%2F65c5f3599faf2d04cd7da528%2Fimages%2Fphoto.jpg"

Example (delete project asset):

curl -v -X DELETE \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/files?path=uploads%2Fprojects%2F65c5f3599faf2d04cd7da528%2Ffiles%2Fuuid%2Flogo.png"

Error Codes

• 400: Bad request - Invalid file, missing parameters, or upload error

• 403: Forbidden - File extension not allowed, content verification failed, or insufficient permissions

• 404: Not found - File or resource not found

• 413: Payload too large - File exceeds maximum upload size (configurable via MAX_UPLOAD_FILE_SIZE environment variable)

• 500: Internal server error - Server error during file operations

File Content Verification

All uploaded files are verified to ensure the file content matches the declared MIME type. This prevents security issues by detecting mismatched file types.

Thumbnail Generation

Images uploaded as assets or user/bot avatars automatically generate 200x200 pixel thumbnails. Thumbnails are stored with the pattern thumbnails_200_200-{original_filename} and are automatically deleted when the main file is deleted.