> For the complete documentation index, see [llms.txt](https://docs.toolhouse.ai/toolhouse/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolhouse.ai/toolhouse/developers/attachments.md). # Attachments Workers support file attachments alongside messages, which you can upload via the [Workers API](/toolhouse/developers/workers-api.md). You can provide attachments either as a publicly accessible URL or as a directly uploaded file encoded in base64. Attachments are supported by both `POST` and `PUT` endpoints. Attachments are different from [Skills & Knowledge](/toolhouse/capabilites/skills-and-knowledge.md). Attachments are uploaded into the user's message. Examples of attachments can be: * If you are building a financial analyst worker, you can send a spreadsheets it will need to analyze to create its financial model. * If you are building a SEO keyword optimizer agent, you can send a CSV with a list of websites to optimize. * For legal counsel workers, you could send Word documents or PDF you'll want them to redline. *** ### General Rules * **Maximum file size:** 10 MB per attachment (applies to both URL and direct uploads). This limit can be increased — use the **Contact us** option in the Toolhouse dashboard to request an upgrade. * **No storage:** attachments are not stored in a file storage facility, and will be sent as is to the worker. * **Data ownership:** You must own the data you submit. All attachments must adhere to the [Toolhouse Terms of Service](https://toolhouse.ai/tos). Abuse will result in account termination. *** ### URL Attachments Provide the fully formed URL to the resource. The URL must be publicly accessible, and our systems must be able to download it within a reasonable timeframe. * **Timeout:** 30 seconds. Downloads that exceed this limit will be skipped and execution will continue without the file. * The URL must include the scheme (e.g. `https://`). ```bash curl -XPOST \ https://agents.toolhouse.ai/$AGENT_ID \ -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \ --json '{ "message": "Summarize this document.", "attachment": { "url": "https://example.com/report.pdf" } }' ``` *** ### Direct Upload Attach the file directly in the request body by encoding it as a base64 string and supplying it in the `attachment` field. {% tabs %} {% tab title="Prompt" %} {% code overflow="wrap" %} ```markdown I'm integrating the Toolhouse Workers API into my codebase. I need a function that accepts a file path as input, reads the file, encodes it as base64, and attaches it to a POST request to `https://agents.toolhouse.ai/$AGENT_ID`. The request body should be JSON with a `message` field and an `attachment` field containing data (the base64 string). Auth is via a Bearer token in the `Authorization` header. Use the conventions and language already used in this codebase, handle errors gracefully, and make the agent ID, API key, and message configurable. ``` {% endcode %} {% endtab %} {% tab title="JavaScript" %} ```typescript const fs = require("fs"); async function callWorkerWithAttachment(agentId, apiKey, filePath, message) { const fileBuffer = fs.readFileSync(filePath); const base64Data = fileBuffer.toString("base64"); const filename = filePath.split("/").pop(); const response = await fetch(`https://agents.toolhouse.ai/${agentId}`, { method: "POST", headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ message, attachment: { data: base64Data, filename, }, }), }); const runId = response.headers.get("x-toolhouse-run-id"); const text = await response.text(); return { runId, text }; } ``` {% endtab %} {% tab title="Shell" %} ```bash FILE_PATH="path/to/your/file.xlsx" FILENAME=$(basename "$FILE_PATH") BASE64_DATA=$(base64 -i "$FILE_PATH") curl -XPOST \ https://agents.toolhouse.ai/$AGENT_ID \ -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \ --json "{ \"message\": \"Analyze this spreadsheet.\", \"attachment\": { \"data\": \"$BASE64_DATA\" } }" ``` {% endtab %} {% endtabs %} *** ### Continuing a Conversation with an Attachment Attachments can be included in `PUT` requests to continue an existing interaction. Use the `X-Toolhouse-Run-ID` from the initial response to maintain context. ```bash # Continue a conversation and include a new attachment curl -XPUT https://agents.toolhouse.ai/$AGENT_ID/$RUN_ID \ -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \ --json '{ "message": "Now summarize this follow-up document.", "attachment": { "url": "https://example.com/follow-up.pdf" } }' ``` *** ### Conversion Behavior When an attachment is received, the endpoint automatically detects its MIME type and processes the file accordingly. * If the file is not a supported type, or if the base64 encoding is invalid, the attachment will be **silently discarded** and execution will continue without it. * No error is returned when an attachment is discarded — check that your file type and encoding are correct if the worker behaves as though no file was provided. *** ### Supported File Types | Category | Extensions | MIME Types | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **PDF files** | `.pdf` | `application/pdf` | | **Spreadsheets** | `.xla`, `.xlb`, `.xlc`, `.xlm`, `.xls`, `.xlsx`, `.xlt`, `.xlw` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/vnd.ms-excel` | | **Spreadsheets** | `.csv`, `.tsv`, `.iif`, Google Sheets | `text/csv`, `application/csv`, `text/tsv`, `text/x-iif`, `application/x-iif`, `application/vnd.google-apps.spreadsheet` | | **Rich documents** | `.doc`, `.docx`, `.dot`, `.odt`, `.rtf`, Pages, Google Docs | `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/msword`, `application/rtf`, `text/rtf`, `application/vnd.oasis.opendocument.text`, `application/vnd.apple.pages`, `application/vnd.google-apps.document`, `application/vnd.apple.iwork` | | **Presentations** | `.pot`, `.ppa`, `.pps`, `.ppt`, `.pptx`, `.pwz`, `.wiz`, Keynote, Google Slides | `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `application/vnd.ms-powerpoint`, `application/vnd.apple.keynote`, `application/vnd.google-apps.presentation`, `application/vnd.apple.iwork` | | **Text and code** | `.asm`, `.bat`, `.c`, `.cc`, `.conf`, `.cpp`, `.css`, `.cxx`, `.def`, `.dic`, `.eml`, `.h`, `.hh`, `.htm`, `.html`, `.ics`, `.ifb`, `.in`, `.js`, `.json`, `.ksh`, `.list`, `.log`, `.markdown`, `.md`, `.mht`, `.mhtml`, `.mime`, `.mjs`, `.nws`, `.pl`, `.py`, `.rst`, `.s`, `.sql`, `.srt`, `.text`, `.txt`, `.vcf`, `.vtt`, `.xml` | `text/plain`, `text/markdown`, `text/html`, `text/css`, `application/json`, `application/javascript`, `application/typescript`, `text/x-python`, `text/x-c`, `text/x-c++`, `text/x-java`, `text/x-go`, `text/x-rust`, `text/x-ruby`, `text/x-sh`, `text/x-bash`, `text/x-php`, `text/x-swift`, `text/x-kotlin`, `text/x-scala`, `text/x-typescript`, `text/x-sql`, `text/x-yaml`, `application/yaml`, `application/x-yaml`, `application/toml`, `application/graphql`, `text/x-dockerfile`, `text/x-ini`, `text/x-toml`, `text/x-hcl`, `text/x-terraform`, `text/x-sass`, `text/x-scss`, `text/x-less`, `text/x-protobuf`, `text/x-r`, `text/x-julia`, `text/x-perl`, `text/x-lua`, `text/x-dart`, `text/x-erlang`, `text/x-elixir`, `text/x-haskell`, `text/x-clojure`, `text/x-groovy`, `text/calendar`, `text/vtt`, `text/x-vcard`, `message/rfc822` |