> 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/files-api.md). # 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](/toolhouse/capabilites/skills-and-knowledge.md). 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. | ```bash 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: ```bash 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: ```json { "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](https://chatgpt.com/toolhouse/capabilites/skills-and-knowledge.md) 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` |