# Upload a file

`POST https://api.chat-data.com/api/v2/upload-file/{chatbotId}`

Canonical: https://www.chat-data.com/api-reference/upload-file

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Upload a file to be used with a chatbot, for example as a `files` attachment in `/chat` or `/live-chat`. The file is stored in the chatbot's folder under its original name. If a file with that name already exists, it is not replaced: nothing is uploaded and the existing file's URL is returned. Uploads count toward the workspace's file storage limit.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| chatbotId | path | string | yes | The unique identifier allocated to the chatbot. |

## Request body (`multipart/form-data`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| file | file | yes | The file to upload. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/upload-file/6650f1c2a9e4b83d2c7a1f05' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -F 'file=@"/path/to/file.pdf"'
```

## Example response (200)

```json
{
  "status": "success",
  "url": "https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/product-handbook.pdf?sv=2024-11-04&se=2026-11-13T09%3A30%3A00Z&sr=b&sp=r&sig=Xq7mB2v9KpL4tR8wN1cZ5yF3hJ6dS0aE%2BuG7iO2kQ%3D"
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | No `file` was sent, or the workspace has reached its file storage limit. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |
| 500 | The file could not be stored; the body also identifies the file. A file sent under a field other than `file` also gets a 500, whose body is not JSON. |