Files and attachments
Use this reference with the complete developer tour and Python types. The example at the end runs after the tour setup.
attachments
Section titled “attachments”List the files currently visible in a conversation.
attachments(self, conversation_id: str)| Parameter | Type and default | Usage |
|---|---|---|
conversation_id |
str (required) |
Canonical conversation ID. Use it to continue the same authorized history. |
Returns: Array of Attachment metadata, not file bytes.
Permissions, lifecycle and errors: Attachment access follows current history visibility. Knowing a file ID never bypasses conversation or membership checks.
Working Python example. Input/output fields are in the types reference.
stage_attachment
Section titled “stage_attachment”Upload a private draft before creating its message, request, chat or batch.
stage_attachment(self, name: str, media: str, data: bytes)| Parameter | Type and default | Usage |
|---|---|---|
name |
str (required) |
Human-readable name. It is not necessarily unique. |
media |
str (required) |
Declared media type, for example application/pdf. |
data |
bytes (required) |
JSON request body for call/Do; raw bytes for Python/Go file upload. |
Returns: Attachment with id to place in attachment_ids.
Permissions, lifecycle and errors: 1 byte to 5 MiB. Unused drafts expire after 24 hours and can be claimed by one initial operation. Uploads are not automatically retried after an unknown outcome.
Working Python example. Input/output fields are in the types reference.
upload_attachment
Section titled “upload_attachment”Upload a file into an already authorized conversation.
upload_attachment(self, conversation_id: str, name: str, media: str, data: bytes)| Parameter | Type and default | Usage |
|---|---|---|
conversation_id |
str (required) |
Canonical conversation ID. Use it to continue the same authorized history. |
name |
str (required) |
Human-readable name. It is not necessarily unique. |
media |
str (required) |
Declared media type, for example application/pdf. |
data |
bytes (required) |
JSON request body for call/Do; raw bytes for Python/Go file upload. |
Returns: Attachment with id, file_name, media_type, size and sha256.
Permissions, lifecycle and errors: Go/Python take bytes plus name/media; TypeScript takes Blob plus name. Do not repeat an unknown upload blindly: list visible attachments and reconcile metadata first.
Working Python example. Input/output fields are in the types reference.
download_attachment
Section titled “download_attachment”Download the bytes of a currently visible attachment.
download_attachment(self, attachment_id: str)| Parameter | Type and default | Usage |
|---|---|---|
attachment_id |
str (required) |
Currently visible Attachment.id. |
Returns: Go []byte, Python bytes, TypeScript Blob.
Permissions, lifecycle and errors: Requires current file/history access. A removed participant may lose access even to an old ID. Transfers are bounded at 5 MiB.
Working Python example. Input/output fields are in the types reference.
Example
Section titled “Example”Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.
pdf = b'%PDF-1.4\nPayment reconciliation fixture\n%%EOF'draft = builder.stage_attachment('orders.pdf', 'application/pdf', pdf)with_file = builder.send(target=target, body='Please check these payment records.', attachment_ids=[draft['id']])listed = billing.attachments(with_file['conversation_id'])assert listed[0]['id'] == draft['id']assert billing.download_attachment(draft['id']) == pdfuploaded = builder.upload_attachment(with_file['conversation_id'], 'notes.txt', 'text/plain', b'Orders 241 and 242')assert uploaded['id'] != draft['id']