---
title: Attachments
description: Send files to an agent, and receive the files it sends back.
---

A message can carry files: a contract to review, a spreadsheet to clean up, a report the agent wrote. A file a message carries is an **attachment**. It is a copy kept with the conversation: it never changes under its id, and it cannot be edited or removed while the session lives.

Attachments are off until an agent's version turns them on:

```json
{ "attachments": { "type": "enabled" } }
```

In the console it is **Attachments**, under **Tools** in the [version editor](/console/agents#the-version-editor). A session takes the setting of the version it runs, and a session another session started never carries files, whatever its version says. The session itself answers its setting as `attachments`.

| | A person's message | The agent's message |
| --- | --- | --- |
| Sends files by | Uploading them, then naming them in the input | Calling `attach` with files from its [Session Volume](/functions/runtime#the-session-volume) |
| Needs | `attachments` enabled | `attachments` enabled, and a version that grants [functions](/functions) |
| Event | `message_user`, with `attachments` | `message_attachments_added`, beside the `message_assistant` that called `attach` |

## Sending files

A file goes up first, on its own, and the input that follows names it.

```bash
# 1. Upload the file. Its name's extension decides its media type.
curl -X POST "https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/uploads?name=q3-review.pdf" \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @q3-review.pdf
```

```json
{
  "id": "01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c",
  "name": "q3-review.pdf",
  "media_type": "application/pdf",
  "bytes": 482113,
  "expires_at": "2026-11-20T18:48:16Z"
}
```

```bash
# 2. Send the message, naming the upload.
curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "input", "text": "Summarize the risks in this review.", "upload_ids": ["01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c"]}'
```

- `name` is one path segment of 1 to 200 bytes, such as `report.pdf`, and the body is the file's bytes, at most 1 GiB.
- An input names at most 20 uploads, and its `text` may be empty when the files alone carry it.
- An upload goes with one message only. Once sent, it is an attachment of that message under the same `id`.
- An upload no message carries is removed at `expires_at`, 24 hours after it was made. Sending it after that answers 404: upload it again.
- A retry of the upload under one `Idempotency-Key`, for the same name and length, answers the first upload rather than storing a second.

The session token uploads, and so does an API key with **Sessions** › **Manage**. A session whose agent does not enable attachments answers 409, and so does one whose attachments and waiting uploads already hold 10 GiB.

## Showing the files

A person's message is `message_user`, and its `attachments` lists the files it carries — an empty array when it carries none:

```json
{
  "type": "message_user",
  "message": { "role": "user", "content": [{ "type": "text", "data": { "text": "Summarize the risks in this review." } }] },
  "source": "client",
  "attachments": [
    { "id": "01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c", "name": "q3-review.pdf", "media_type": "application/pdf", "bytes": 482113 }
  ]
}
```

The files the agent attaches arrive as `message_attachments_added`. Its `call_id` is the `attach` call that made it, so show the files under the `message_assistant` that holds that call:

```json
{
  "type": "message_attachments_added",
  "call_id": "call_7d1e",
  "attachments": [
    { "id": "01a087a2-0b4c-7e21-9c3d-6f5e4d3c2b1a", "name": "risks.md", "media_type": "text/markdown", "bytes": 3912 }
  ]
}
```

Either way, a file's bytes are at:

```bash
curl https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/attachments/$ATTACHMENT_ID \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -o q3-review.pdf
```

The response is typed as the attachment's `media_type` and always served as a download, whatever the file holds. The bytes never change under an id, so a client may cache them for as long as it likes. An API key needs **Sessions** › **Read**.

## With the TypeScript SDK

A session connection's `send` uploads the files and names them in one call. Each file goes up once, however often the turn is retried:

```ts
await session.send("Summarize the risks in this review.", { files: [file] });
```

To upload ahead of sending — while the person is still typing, say — call `upload`, and pass the ids it answers as `uploadIds`:

```ts
const upload = await session.upload(file, { name: file.name });
await session.send("", { uploadIds: [upload.id] });
```

`readAttachment` downloads a file by the `id` an `attachments` entry names — from `message_user` or `message_attachments_added` — and answers a `Blob` typed as its `media_type`. In a browser, hand it to the person under the file's own name:

```ts
const blob = await session.readAttachment(attachment.id);
const url = URL.createObjectURL(blob);
const link = Object.assign(document.createElement("a"), { href: url, download: attachment.name });
link.click();
setTimeout(() => URL.revokeObjectURL(url), 0);
```

The same object URL can be an `<img>`'s `src` to show an image. A backend with an API key reaches the same file without a connection, as `client.sessions.readAttachment(sessionId, attachmentId)`.

In `@subako-ai/assistant-ui`, `allowAttachments` adds an attach button to the composer of the ready-made chat, and turns on the runtime's attachment adapter for a thread of your own.

## What the agent can do with them

A version that enables attachments is served the built-in tools of `builtin:attachments`, with no policy: enabling attachments is the decision.

| Tool | Offered | What it does |
| --- | --- | --- |
| `builtin__attachments__read` | Always | Reads an attachment. Text comes back a part at a time — by lines, 200 at a time unless asked for up to 10,000, or by bytes — at most 256 KiB per call. An image is shown to the model. |
| `builtin__attachments__copy_to_volume` | When the version grants functions | Copies an attachment into the [Session Volume](/functions/runtime#the-session-volume), such as `/volume/tmp/report.pdf`, for its functions to work on. |
| `builtin__attachments__attach` | When the version grants functions | Attaches up to 20 files from the volume, each at most 1 GiB, to the agent's own message. |

The model is told each file a person sends as an `<attachment id="…" name="…" media_type="…" bytes="…"/>` line of their message, and reads it only when it decides to. What `read` cannot show — a PDF, a spreadsheet — the agent copies into the volume and converts with a function, such as the [platform's packages](/functions/platform-packages).

`attach` copies each file as it is when called: the attachment stays as it was whatever later happens to the volume, and the agent knows it by the id `attach` answered.

## Limits, retention, and billing

| | |
| --- | --- |
| Files per message | 20, from a person's input or from one `attach` call |
| One file | 1 GiB |
| One session | 10 GiB of attachments and waiting uploads; past that, a new upload or `attach` is refused |
| An upload no message carries | Removed 24 hours after it was made |
| An attachment | Kept until its session is deleted |

A session's attachments and waiting uploads are billed as storage, by the bytes they hold and for as long as they are held, until they are removed. The price is in [Plan and usage](/console/plan-and-usage#what-is-billed).
