Attachments

Attachments let a user add an image or document to a composer before sending a message. Assistant Cloud issues a short lived upload URL, stores the object under the project, and keeps a signed read URL fresh wherever a message is listed or viewed.

How an attachment moves through the composer

The cloud thread list adapter supplies CloudFileAttachmentAdapter as its attachment adapter. Its picker accepts *, then the upload flow decides whether the selected file is supported.

An upload error changes the attachment to an incomplete error state. The adapter checks for cancellation at every stage, so an attachment that the user removes does not progress to the ready to send state.

Accepted files and storage

The upload route accepts these content types. Send content_type explicitly when the filename does not carry a supported extension. Otherwise the route uses the extension fallback.

The upload request has these limits and naming rules.

The object store is private. Attachment URLs are replaced with signed reads rather than treated as durable read credentials. The message list route replaces every recognized attachment URL with a fresh 15 minute signed read. The project wide message list does the same, and the dashboard's thread page signs attachment URLs before it renders the message.

What the dashboard shows

The dashboard's thread page renders the stored transcript in Conversation and includes Raw messages for the stored message payload. Images reach that transcript as image parts. Other uploads reach it as file parts with their MIME type and filename. The thread page replaces attachment URLs with signed reads before rendering them.

From your code

The default adapter is CloudFileAttachmentAdapter. The cloud thread list adapter creates one as its attachments adapter, and the class accepts an AssistantCloud instance or a getter for one. Replace that attachment adapter when your application needs a different picker or upload flow while retaining the cloud thread history adapter.

Outside a composer, use cloud.files to request the same upload and read URLs. The upload URL is for the object transfer only. Your application decides when to put the returned URL into a message part.

const upload = await cloud.files.generatePresignedUploadUrl({
  filename: file.name,
});

await fetch(upload.signedUrl, {
  method: "PUT",
  body: file,
  headers: { "Content-Type": file.type },
});

const download = await cloud.files.generatePresignedDownloadUrl(
  upload.key ? { key: upload.key } : { url: upload.publicUrl },
);

The upload URL is signed for the content type the cloud derives from the filename extension, so the PUT must send that type; for a browser File with a standard extension that is file.type. generatePresignedUploadUrl returns { success, signedUrl, expiresAt, publicUrl, key }, and a response without key is read through the legacy url form. generatePresignedDownloadUrl accepts either { key } or the legacy { url } form and returns { signedUrl, expiresAt, key }.

You can make the same requests directly. The upload route creates a presigned URL, while the download route turns one project owned object key, or one legacy URL, into a new read URL.

POST /v1/files/attachments/generate-presigned-upload-url
Authorization: Bearer <token>
Content-Type: application/json

{
  "filename": "architecture.pdf",
  "content_type": "application/pdf",
  "content_length": 248921
}

{
  "success": true,
  "signedUrl": "https://…",
  "expiresAt": "2026-09-17T10:15:00.000Z",
  "publicUrl": "https://…",
  "key": "attachments/proj_0…/5de26af4-….pdf"
}

POST /v1/files/attachments/generate-presigned-download-url
Authorization: Bearer <token>
Content-Type: application/json

{ "key": "attachments/proj_0…/5de26af4-….pdf" }

{
  "signedUrl": "https://…",
  "expiresAt": "2026-09-17T10:15:00.000Z",
  "key": "attachments/proj_0…/5de26af4-….pdf"
}

The download request requires exactly one of key or the legacy url. A key outside attachments/<projectId>/, or a URL that does not parse as a configured attachment URL, returns 404 with Attachment not found.

Events, costs, and limits

The runtime records an attachment_added client event when the composer emits composer.attachmentAdd. It records attachment_failed when the composer emits composer.attachmentAddError. Each event includes props.type with the content type when it is known.

Retention deletes the messages that reference an attachment; the stored object itself is not part of the retention pass.

Troubleshooting