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
The Project Id is a unique code assigned to your project when you create it in Tiledesk.
Query Parameters
Optional. Expiration time in seconds. If provided and greater than 0, the file will expire after this time.
Authorization token. Basic Auth or JWT. Minimum role: admin
Use "multipart/form-data" value
The binary file to upload. Must match allowed extensions for assets. Images will automatically generate thumbnails.
Example:
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
The Project Id is a unique code assigned to your project when you create it in Tiledesk.
Authorization token. Basic Auth or JWT.
Use "multipart/form-data" value
The binary file to upload.
Example:
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
The Project Id is a unique code assigned to your project when you create it in Tiledesk.
Query Parameters
Optional. If provided, uploads the avatar for the specified bot. The authenticated user must be an admin or owner of the bot's project.
Authorization token. Basic Auth or JWT. Minimum role: agent
Use "multipart/form-data" value
The image file to upload. Must be one of: .png, .jpg, .jpeg, .gif
Example (user photo):
Example (bot avatar):
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
The file path (URL encoded). Example: uploads/projects/5ebd890292befe0019054973/files/uuid/document.pdf
Optional. If set, the file will be returned with Content-Disposition header set to attachment, forcing download.
Authorization token. Basic Auth or JWT
Example:
Example (as attachment):
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
The file path (URL encoded). Example: uploads/projects/5ebd890292befe0019054973/files/uuid/document.pdf
Authorization token. Basic Auth or JWT
Example:
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
The file path (URL encoded). Example: uploads/users/65c5f3599faf2d04cd7da528/images/photo.jpg or uploads/projects/65c5f3599faf2d04cd7da528/files/uuid/logo.png
Authorization token. Basic Auth or JWT
Example (delete user photo):
Example (delete project asset):
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.
