> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatnorris.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload attachment

> Upload an image or a PDF to send it later to an agent in a chat message.

# Upload attachment

Uploads a file (image or PDF) to attach it to a message. The response returns a `{ url, name, type }` object that you pass as-is in the `attachment` field of [Send message](https://docs.chatnorris.ai/en/api-referencia/agentes/chat.md). The file isn't sent in the chat body: first you upload it with this endpoint and then you reference it by its URL.

Uploading a file doesn't consume credits. The cost is charged when you send the message.

```http theme={null}
POST https://app.chatnorris.ai/api/v2/chatbots/{chatbot_id}/attachments
Authorization: Bearer <your_api_key>
Content-Type: multipart/form-data
```

**Required scope:** `chat:write`

***

## Path parameters

| Parameter | Type | Description |
| - | - | - |
| `chatbot_id` | string | ID of the agent the attachment will be sent to |

***

## Request body

The body must be `multipart/form-data` with a single field:

| Field | Type | Required | Description |
| - | - | - | - |
| `file` | file | ✅ | The file to upload. The type is taken from the `Content-Type` of the form part. |

### Allowed types and sizes

| Type | `Content-Type` | Maximum size |
| - | - | - |
| PNG image | `image/png` | 5 MB |
| JPEG image | `image/jpeg` | 5 MB |
| WebP image | `image/webp` | 5 MB |
| GIF image | `image/gif` | 5 MB |
| PDF | `application/pdf` | 15 MB |

***

## Response

**Code:** `201 Created`

```json theme={null}
{
  "status": "success",
  "data": {
    "url": "https://<project>.supabase.co/storage/v1/object/public/chat-attachments/...",
    "name": "invoice.pdf",
    "type": "application/pdf"
  }
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `url` | string | URL of the uploaded file. Pass it in `attachment.url` when you send the message. |
| `name` | string | Original file name (max. 200 characters). Omitted if the file has no name. |
| `type` | string | Normalized file type (for example, `image/jpg` is returned as `image/jpeg`). |

***

## Full example: upload and send

**1. Upload the file**

```bash theme={null}
curl -X POST "https://app.chatnorris.ai/api/v2/chatbots/{chatbot_id}/attachments" \
  -H "Authorization: Bearer <your_api_key>" \
  -F "file=@invoice.pdf;type=application/pdf"
```

**2. Send the message with the attachment**

Use the `data` object from the previous response as `attachment`. The `message` field is still required.

```bash theme={null}
curl -X POST "https://app.chatnorris.ai/api/v2/chatbots/{chatbot_id}/chat" \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you tell me the total on this invoice?",
    "attachment": {
      "url": "https://<project>.supabase.co/storage/v1/object/public/chat-attachments/...",
      "name": "invoice.pdf",
      "type": "application/pdf"
    }
  }'
```

> [!NOTE]
>
> Only attachments uploaded with this endpoint are processed. If `attachment.url` points to another site, the agent can't see the file.

***

## Common errors

| HTTP | Code | Description |
| - | - | - |
| 400 | `INVALID_INPUT` | The body isn't `multipart/form-data` or the `file` field is missing |
| 400 | `INVALID_FILE_TYPE` | The file type isn't PNG, JPEG, WebP, GIF or PDF |
| 400 | `FILE_TOO_LARGE` | The file exceeds the limit for its type (5 MB images, 15 MB PDF) |
| 403 | `INSUFFICIENT_SCOPE` | The API key doesn't have the `chat:write` scope |
| 404 | `NOT_FOUND` | The agent doesn't exist, is inactive or doesn't belong to your organization |
| 429 | `RATE_LIMIT_EXCEEDED` | The API key's requests-per-minute limit was exceeded |
| 500 | `INTERNAL_ERROR` | The file couldn't be saved |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.