# 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` | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.toolhouse.ai/toolhouse/developers/attachments.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.