---
title: Passing files
description: How file objects move between blocks, into workflows via the API, and back out in responses.
pageType: guide
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

A file moves through a workflow as a standardized **file object**. Blocks receive it, act on it, and pass it on — this page covers the object's shape, how to reference it between blocks, and how files enter and leave through the API.

## File Objects

When blocks output files (like Gmail attachments, generated images, or parsed documents), they return a standardized file object:

```json
{
  "id": "f_8c2...",
  "name": "report.pdf",
  "url": "https://...",
  "size": 245678,
  "type": "application/pdf",
  "base64": "JVBERi0xLjQK..."
}
```

You can access any of these properties when referencing files from previous blocks.

## The File Block

The **File block** brings a file into a workflow. It accepts files from any source and outputs standardized file objects every block understands.

**Inputs:**
- **Uploaded files** - Drag and drop or select files directly
- **External URLs** - Any publicly accessible file URL
- **Files from other blocks** - Pass files from Gmail attachments, Slack downloads, etc.

**Outputs:**
- A list of `UserFile` objects with consistent structure (`id`, `name`, `url`, `size`, `type`, `base64`)
- `contents` - Extracted text per file (the Get Content operation)
- `combinedContent` - All fetched files' text merged into one string (the Fetch operation)

**Example usage:**

```
// Get all files from the File block
<file.files>

// Get the first file
<file.files[0]>

// Get the first file's extracted text (Get Content operation)
<file.contents[0]>
```

The File block automatically:
- Detects file types from URLs and extensions
- Extracts text from PDFs, CSVs, and documents
- Generates base64 encoding for binary files
- Creates presigned URLs for secure access

Use the File block when you need to normalize files from different sources before passing them to other blocks like Vision, STT, or email integrations.

## Passing Files Between Blocks

Reference files from previous blocks using the tag dropdown. Click in any file input field and type `<` to see available outputs.

**Common patterns:**

```
// Single file from a block
<gmail.attachments[0]>

// Pass the whole file object
<file_parser.files[0]>

// Access specific properties
<gmail.attachments[0].name>
<gmail.attachments[0].base64>
```

Most blocks accept the full file object and extract what they need automatically. You don't need to manually extract `base64` or `url` in most cases.

## Triggering Workflows with Files

When calling a workflow via API that expects file input, include files in your request:

<Tabs items={['Base64', 'URL']}>
  <Tab value="Base64">
    ```bash
    curl -X POST "https://sim.ai/api/workflows/YOUR_WORKFLOW_ID/execute" \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "document": {
          "name": "report.pdf",
          "base64": "JVBERi0xLjQK...",
          "type": "application/pdf"
        }
      }'
    ```
  </Tab>
  <Tab value="URL">
    ```bash
    curl -X POST "https://sim.ai/api/workflows/YOUR_WORKFLOW_ID/execute" \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "document": {
          "name": "report.pdf",
          "url": "https://example.com/report.pdf",
          "type": "application/pdf"
        }
      }'
    ```
  </Tab>
</Tabs>

The workflow's Start block should have an input field configured to receive the file parameter.

## Receiving Files in API Responses

When a workflow outputs files, they're included in the response:

```json
{
  "success": true,
  "output": {
    "generatedFile": {
      "name": "output.png",
      "url": "https://...",
      "base64": "iVBORw0KGgo...",
      "type": "image/png",
      "size": 34567
    }
  }
}
```

Use `url` for direct downloads or `base64` for inline processing.

## Blocks That Work with Files

**File inputs:**
- **File** - Parse documents, images, and text files
- **Agent** - Read images with a vision-capable model, or documents as text
- **Mistral Parser** - Extract text from PDFs

**File outputs:**
- **Gmail** - Email attachments
- **Slack** - Downloaded files
- **TTS** - Generated audio files
- **Video Generator** - Generated videos
- **Image Generator** - Generated images

**File storage:**
- **Supabase** - Upload/download from storage
- **S3** - AWS S3 operations
- **Google Drive** - Drive file operations
- **Dropbox** - Dropbox file operations

<Callout type="info">
  Files are automatically available to downstream blocks. The engine handles all file transfer and format conversion.
</Callout>

## Best Practices

1. **Use file objects directly** - Pass the full file object rather than extracting individual properties. Blocks handle the conversion automatically.

2. **Check file types** - Ensure the file type matches what the receiving block expects. An Agent using a vision-capable model can read images, while the File block handles documents.

3. **Consider file size** - Large files increase run time. For very large files, consider using storage blocks (S3, Supabase) for intermediate storage.

import { FAQ } from '@/components/ui/faq'

<FAQ items={[
  { question: "What is the maximum file size for uploads?", answer: "The maximum file size for files processed during a workflow run is 20 MB. Files exceeding this limit will be rejected with an error indicating the actual file size. For larger files, use storage blocks like S3 or Supabase for intermediate storage." },
  { question: "What file input formats are supported via the API?", answer: "When triggering a workflow via API, you can send files as base64-encoded data (using a data URI with the format 'data:{mime};base64,{data}') or as a URL pointing to a publicly accessible file. In both cases, include the file name and MIME type in the request." },
  { question: "How are files passed between blocks internally?", answer: "Files are represented as standardized UserFile objects with name, url, base64, type, and size properties. Most blocks accept the full file object and extract what they need automatically, so you typically pass the entire object rather than individual properties." },
  { question: "Do I need to extract base64 or URL from file objects manually?", answer: "No. Most blocks accept the full file object and handle the format conversion automatically. Simply pass the entire file reference (e.g., <gmail.attachments[0]>) and the receiving block will extract the data it needs." },
  { question: "How do file fields work in the Start block's input format?", answer: "When you define a field with type 'file[]' in the Start block's input format, the engine automatically processes incoming file data (base64 or URL) and uploads it to storage, converting it into UserFile objects before the workflow runs." },
]} />
