Attachments
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:
{ "attachments": { "type": "enabled" } }
In the console it is Attachments, under Tools in 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 |
| Needs | attachments enabled |
attachments enabled, and a version that grants 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.
# 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
{
"id": "01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c",
"name": "q3-review.pdf",
"media_type": "application/pdf",
"bytes": 482113,
"expires_at": "2026-11-20T18:48:16Z"
}
# 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"]}'
nameis one path segment of 1 to 200 bytes, such asreport.pdf, and the body is the file’s bytes, at most 1 GiB.- An input names at most 20 uploads, and its
textmay 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:
{
"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:
{
"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:
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:
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:
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:
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, 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.
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.