---
title: Files and pictures in a chat
description: Attach pictures, Word documents and text or code files to a quick chat's message (or a chat with a bot), by picking, pasting or dropping them, and the agent reads them.
section: agents
order: 7
audience: [user, builder]
sources: [services/nodejs-cloud/lib/agents/attachments.ts, services/nodejs-cloud/lib/agents/attachments-pure.ts, services/nodejs-cloud/components/agents/attach.ts, services/nodejs-cloud/components/agents/Composer.tsx, services/nodejs-cloud/app/api/workspace/agents/attachments, services/nodejs-cloud/migrations/0376_agent_chat_files.sql]
features: []
---

A [quick chat](/docs/agents/quick-chat.md), and a [chat with a bot](/docs/agents/bots.md#chat-with-a-bot), can take files and pictures with a
message. The agent sees a picture as a picture and reads a document or a text file as text.

## Attach

In the prompt box, on a new chat or an open one:

- **Pick**: the paperclip opens the file picker. On a phone it also offers the camera and the photo library.
- **Paste**: paste a picture (a screenshot) into the box. Pasted text stays text.
- **Drop**: drag files anywhere onto the chat.

Each file shows above the text while it uploads, with its progress. A file that can't be attached says why on its chip;
remove it with its ×. Send works once the uploads finish. A message can be files alone, with no words.

Pictures larger than 1568 pixels on their longest side are shrunk in your browser before they upload. That is about what the
models look at anyway, and it keeps a phone photo small.

Code chats and computer chats take text only for now.

## What can be attached

| Kind | Types | What the agent gets |
|---|---|---|
| Pictures | PNG, JPEG, WebP, GIF | the picture itself, in the message it came with |
| Word documents | `.docx` | its text, as markdown (headings, lists, tables, links) |
| Text and code | `.txt`, `.md`, `.csv`, `.json`, `.yaml`, `.log`, `.html`, `.xml`, `.sql`, and source files (`.ts`, `.py`, `.go`, `.rs`, `.java`, `.c`, …) | its text |

The type is read from the file's bytes, never from its name or the type your browser claims. A PNG named `notes.txt` is a
picture; text named `cat.png` is refused. A text file must be UTF-8 text and end in one of the extensions above. Anything
else is refused when you attach it, with the reason, and is never kept:

- **PDF**: not yet. Paste its text, or attach it as `.docx` or a text file.
- **SVG**, archives, spreadsheets, audio, video and other binary files.

## Limits

| Limit | Value |
|---|---|
| One file | 4 MB |
| One picture | 3 MB, and at most 8000 pixels on its longest side |
| Files in one message | 6 |
| Files in one chat | 50 |
| Files uploaded but not sent yet | 20; removed after a day |
| A text file's text given to the model | the first 30,000 characters, and 60,000 for all of a message's files; the agent is told what was cut |
| A text file's text kept | the first 200,000 characters |
| Pictures sent to the model in one request | the newest 8, up to 5 MB together |

Files count toward your organisation's files quota, the same 1 GB that Venom Notes uploads use.

## How the agent sees them

Every turn, the agent gets the conversation again from the stored chat. A picture goes with the message it came in, so the
agent can still look at it on later turns without you attaching it again. To keep each request bounded, only the newest
8 pictures (5 MB together, which keeps a request under every provider's size limit) are sent. An older picture becomes a line such as `[image: screen.png — an earlier picture, no
longer shown to save space…]`, and the agent can ask you to attach it again. Text files stay in the conversation until the
chat grows past what is sent to the model (see [Limits](/docs/agents/quick-chat.md#limits)); then the oldest messages go first, files
with them.

Files never change the agent's instructions or its tools, only the message they came with.

### A model that doesn't read pictures

Each gear's model either reads pictures or doesn't, as your organisation's models say. When a picture waits in the prompt
box and the chat's gear is known not to read pictures, the box says so: pick a gear that does, from the gear picker. You can
still send it. If the provider refuses the picture, its words show in the chat with a line saying the model may not read
pictures. Text files work on every gear.

## Who can see them

A chat's files are as private as the chat: you, and your organisation's admins (who can read every member's chats). Nobody
else in the organisation can open them, and nothing of another organisation can. A bot's runs work in their own chats and
never see the files of your other chats.

A picture opens larger in the page; any other file downloads. Files are always served with their checked type and never
as a page: a text file comes back as text to download, not as HTML.

Archiving a chat keeps its files with it (you can still read an archived chat), and they keep counting toward the files
quota. Chats can't be deleted yet, so a sent file stays as long as the organisation does; a file you remove from the prompt
box before sending is deleted at once.

## API and MCP

| Route | MCP tool | Does |
|---|---|---|
| `POST /api/workspace/agents/attachments` (raw bytes with the name in `x-file-name`, or multipart field `file`) | `agents_attachment_upload` `{name, base64}` (up to 1 MB in one call) | Upload one file for your next message; answers `{attachment: {id, name, mime, size, kind, width?, height?, text_chars}}` (201). |
| `DELETE /api/workspace/agents/attachments/{id}` | `agents_attachment_delete` | Remove a file you uploaded and have not sent. |
| `POST /api/workspace/agents/chats/{id}/prompt` `{message, attachments: [ids]}` | `agents_chat_send` with `attachments` | Send a message with files. `message` may be empty when there are files. |
| `POST /api/workspace/agents/chats` `{prompt?, attachments: [ids], …}` | `agents_chat_create` with `attachments` | Start a quick chat whose first message has files. |
| `GET /api/workspace/agents/chats/{id}/attachments` | `agents_attachment_list` (and `agents_chat_get`, which lists them too) | The chat's files. |
| `GET /api/workspace/agents/chats/{id}/attachments/{fid}` | (none: the bytes are for the browser) | A file: a picture inline, anything else as a download (`?download` always downloads). |

In the event stream and the transcript, a user message carries its files as `attachments`: `{id, name, mime, size, kind}`
with `kind` `image` or `text`, and `width` and `height` for a picture. The bytes are stored in the cloud's database
(migration 0376, `agent_chat_files`).
