Files API

The Files API lets you upload files and make them available to an agent when it runs. Files are useful when an agent needs to work with specific documents, spreadsheets, or other files provided at runtime.

Files are different from Skills & Knowledge. Skills & Knowledge are part of an agent's persistent capabilities and context, while files are provided for a specific agent run.

For example, you can provide:

• Spreadsheets an agent needs to analyze

• CSV files containing data to process

• Images to edit or turn into videos

• Other supported documents or text files needed for a task

How it works

The Files API uses a two-step workflow:

1. Upload one or more files using the /v1/files/server-uploads endpoint.

2. Use the returned file IDs in the payload when calling your agent.

3. Consume the agent's streaming response.

A file can be attached to an agent by including its file ID in the files array of the agent request. You can attach multiple files to a single agent run.

Upload a file

Upload a file using the /v1/files/server-uploads endpoint.

The request accepts these fields:

Field	Required	Description
data_base64	Yes	The file contents encoded as base64
filename	No	The name of the file. If you don't provide this value, Toolhouse will assign a random name to your file.
mime_type	No	The file's MIME type. If you don't provide this value, Toolhouse will try to determine it by inspecting the file. If a MIME type cannot be determined, the upload will fail.

curl --url 'https://api.toolhouse.ai/v1/files/server-uploads' \
  -H 'Authorization: Bearer BEARER_TOKEN' \
  --data-raw '{
    "filename": "SEO keywords by country.xlsx",
    "data_base64": "FILE_IN_BASE64"
  }'

The response contains the file ID. Save this ID so you can include it in the subsequent agent request.

Attach files to an agent

Once you have uploaded your files, include their IDs in the files array when calling your agent.

You can attach multiple files to the same request:

curl --url 'https://agents.toolhouse.ai/AGENT_ID' \
  -H 'Authorization: Bearer BEARER_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{
    "message": "How are these two files related?",
    "files": [
      {
        "id": "8d0ac872-254a-49b7-91bf-f4a8fe4eaf49"
      },
      {
        "id": "8fdd310b-5dbb-4539-874c-1e4c5a038aa0"
      }
    ]
  }'

The agent processes the files together with the message and returns a response.

Complete workflow

A typical integration looks like this:

Your application
      │
      │ 1. Upload file(s)
      ▼
POST /v1/files/server-uploads
      │
      │ 2. Receive file IDs
      ▼
File IDs
      │
      │ 3. Include IDs in agent request
      ▼
POST /:your-agent-id or /ndjson/:your-agent-id
      │
      │ 4. Consume streaming response
      ▼
Plain or NDJSON response

You can upload files independently of an agent run and then use their IDs when you are ready to execute the agent.

Multiple files

There is no need to combine files before uploading them. Upload each file separately, then include all returned IDs in the same files array.

For example, an agent could receive:

{
  "files": [
    {
      "id": "file-id-1"
    },
    {
      "id": "file-id-2"
    }
  ]
}

The agent can then use both files as part of the same run.

Files vs. Skills & Knowledge

Files are intended for data that is provided to an agent at runtime.

Skills & Knowledge are different: they define what an agent knows or can do independently of a particular file upload.

Use Files when:

• The data changes from one run to another.

• A user provides a document for the agent to process.

• You need to analyze a specific spreadsheet, CSV, PDF, or other file.

• Multiple files need to be processed together in one run.

Use Skills & Knowledge when:

• The agent needs persistent knowledge or capabilities.

• The same information should be available across runs.

• You are defining how an agent performs a particular type of task.

---

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