# 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

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}

{% tab title="400 Bad request - Invalid file or upload error" %}

```
{
  "success": false,
  "error": "Error message"
  "code": "Error code" // code is not always returned
}
```

{% endtab %}

{% tab title="403 Forbidden - File extension not allowed or content verification failed" %}

```
{
  "success": false,
  "error": "File extension .exe is not allowed"
}
```

{% endtab %}

{% tab title="413 File too large" %}

```
{
  "success": false,
  "error": "File too large",
  "code": "LIMIT_FILE_SIZE"
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u user@example.com:password \
  -F file=@logo.png \
  https://api.tiledesk.com/v3/files/assets?expiration=86400
```

## Upload a chat file

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="201 File uploaded successfully" %}

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

{% endtab %}

{% tab title="400 Bad request - Invalid file or upload error" %}

```
{
  "success": false,
  "error": "Error message",
  "code": "Error code"
}
```

{% endtab %}

{% tab title="403 Forbidden - File extension not allowed or content verification failed" %}

```
{
  "success": false,
  "error": "File extension .exe is not allowed"
}
```

{% endtab %}

{% tab title="413 File too large" %}

```
{
  "success": false,
  "error": "File too large",
  "code": "LIMIT_FILE_SIZE"
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u user@example.com:password \
  -F file=@document.pdf \
  https://api.tiledesk.com/v3/files/chat
```

## Upload user profile photo or bot avatar

<mark style="color:green;">`POST`</mark> `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` |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}

{% tab title="400 Bad request - No file uploaded or invalid file" %}

```
{
  "success": false,
  "error": "No file uploaded"
}
```

{% endtab %}

{% tab title="401 Unauthorized - User doesn" %}

```
{
  "success": false,
  "error": "You don't belong to the chatbot's project"
}
```

{% endtab %}

{% tab title="403 Forbidden - Insufficient permissions or file extension not allowed" %}

```
{
  "success": false,
  "error": "You don't have the role required to modify the chatbot"
}
```

{% endtab %}

{% tab title="404 Chatbot not found" %}

```
{
  "success": false,
  "error": "Chatbot not found"
}
```

{% endtab %}

{% tab title="413 File too large" %}

```
{
  "success": false,
  "error": "File too large",
  "code": "LIMIT_FILE_SIZE"
}
```

{% endtab %}
{% endtabs %}

Example (user photo):

```
curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u user@example.com:password \
  -F file=@photo.jpg \
  https://api.tiledesk.com/v3/files/users/photo
```

Example (bot avatar):

```
curl -v -X POST \
  -H 'Content-Type: multipart/form-data' \
  -u user@example.com: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

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="200 File stream" %}

```
<binary content>
```

{% endtab %}

{% tab title="404 File not found" %}

```
{
  "success": false,
  "error": "File not found."
}
```

{% endtab %}

{% tab title="500 Error getting file" %}

```
{
  "success": false,
  "error": "Error getting file."
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X GET \
  -u user@example.com:password \
  "https://api.tiledesk.com/v3/files?path=uploads%2Fprojects%2F5ebd890292befe0019054973%2Ffiles%2Fuuid%2Fdocument.pdf"
```

Example (as attachment):

```
curl -v -X GET \
  -u user@example.com: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

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="200 File download" %}

```
<binary content>
```

{% endtab %}

{% tab title="404 File not found" %}

```
{
  "success": false,
  "error": "File not found."
}
```

{% endtab %}

{% tab title="500 Error getting file" %}

```
{
  "success": false,
  "error": "Error getting file."
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X GET \
  -u user@example.com:password \
  "https://api.tiledesk.com/v3/files/download?path=uploads%2Fprojects%2F5ebd890292befe0019054973%2Ffiles%2Fuuid%2Fdocument.pdf"
```

## Delete a file

<mark style="color:red;">`DELETE`</mark> `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 |

{% tabs %}
{% tab title="200 File deleted successfully" %}

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

{% endtab %}

{% tab title="400 Bad request - Path parameter missing or invalid" %}

```
{
  "success": false,
  "error": "Path parameter is required"
}
```

{% endtab %}

{% tab title="404 File not found" %}

```
{
  "success": false,
  "error": "File not found."
}
```

{% endtab %}

{% tab title="500 Error deleting file" %}

```
{
  "success": false,
  "error": "Error deleting file."
}
```

{% endtab %}
{% endtabs %}

Example (delete user photo):

```
curl -v -X DELETE \
  -u user@example.com:password \
  "https://api.tiledesk.com/v3/files?path=uploads%2Fusers%2F65c5f3599faf2d04cd7da528%2Fimages%2Fphoto.jpg"
```

Example (delete project asset):

```
curl -v -X DELETE \
  -u user@example.com: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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tiledesk.com/apis/rest-api/files.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.