Passing Files

SteelEngine makes it easy to work with files throughout your workflows. Blocks can receive files, process them, and pass them to other blocks seamlessly.

File Objects

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

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

You can access any of these properties when referencing files from previous blocks. base64 is optional: it is present only when the file was produced with inline content or hydrated for an API response (see Receiving Files in API Responses).

The Docs Block

The Docs block is the universal entry point for files in your workflows. Its Read Docs operation accepts files from any source and outputs standardized file objects that work with all integrations. The same block can also write and append workspace docs.

Operations:

  • Read Docs - Parse uploaded docs or a doc URL into file objects and extracted text
  • Write Doc - Create a new workspace doc from text content
  • Append Doc - Add content to the end of an existing workspace doc

Read Docs inputs:

  • Docs - Select or upload files directly
  • Doc URL (under Advanced) - Any publicly accessible file URL
  • Files from other blocks - Pass files from Gmail attachments, Slack downloads, etc.

Read Docs outputs:

  • files - A list of UserFile objects with consistent structure (id, name, url, type, size, and base64 when available)
  • combinedContent - Extracted text content from all files (for documents)

Write Doc and Append Doc outputs:

  • id, name, size, and url of the doc that was written (Write Doc also returns folderId)

Example usage:

// Get all files from the Docs block
<docs.files>

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

// Get combined text content from parsed documents
<docs.combinedContent>

Read Docs parses text, PDF, CSV, and image files from uploads or URLs. Use it when you need to normalize files from different sources before passing them to other blocks like Vision, STT, or email integrations. The Docs tool reference lists every input and output.

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
<docs.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:

curl -X POST "https://dev.steelengine.com/api/workflows/YOUR_WORKFLOW_ID/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "document": [
      {
        "type": "file",
        "name": "report.pdf",
        "mime": "application/pdf",
        "data": "data:application/pdf;base64,JVBERi0xLjQK..."
      }
    ]
  }'

Each file is an object with type, name, data, and an optional mime. With type: "file", data is a data URI in the form data:<mime>;base64,<data>. With type: "url", data is a publicly reachable URL. Send one object or an array. SteelEngine rejects files larger than 20 MB.

The workflow's Start block needs an Input Format field of type Docs (file[]) with the same name as the request key (document above). SteelEngine uploads the files to storage and replaces the field value with UserFile objects before the workflow runs.

Receiving Files in API Responses

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

{
  "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. SteelEngine includes base64 by default for files up to 10 MB. Send "includeFileBase64": false in the request body to leave it out. Set "base64MaxBytes" to change the per-file size cap. Larger files still return their url.

Blocks That Work with Files

File inputs:

  • Docs (Read Docs) - Parse documents, images, and text files
  • Vision - Analyze images with AI models
  • 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

Files are automatically available to downstream blocks. The execution engine handles all file transfer and format conversion.

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. The Vision block needs images, the Docs block handles documents.

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

Common Questions

The maximum file size for files processed during workflow execution 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.
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.
Files are represented as standardized UserFile objects with id, name, url, type, size, and (when available) base64 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.
Gmail outputs email attachments, Slack outputs downloaded files, TTS generates audio files, Video Generator and Image Generator produce media files. Storage blocks like S3, Supabase, Google Drive, and Dropbox can also retrieve files for use in downstream blocks.
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.
When you define a field with type 'file[]' in the Start block's input format, the execution engine automatically processes incoming file data (base64 or URL) and uploads it to storage, converting it into UserFile objects before the workflow runs.

On this page