Attachments

Workers support file attachments alongside messages, which you can upload via the Workers API. 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. 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. 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://).

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.

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.

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 };
}

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\"
    }
  }"

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.

# 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

PreviousWorker statefulness NextTavily (Official Partner)

Last updated 27 days ago