Files

When a workflow input is a file, the SDK uploads it as multipart/form-data (the same shape as curl -F). No base64, no payload doubling. When the aggregate multipart payload (all file bytes plus form envelope headroom) would exceed ~4 MB, maintained client.run(...) helpers pre-upload enough files through the Files API (storage-direct on cloud, multipart fallback on-prem) with purpose: "run-input" and send {"$fileId": "file_..."} so cloud deployments stay under Vercel’s request-body limit. The server keeps those temporary pool files available for safe run-start retries and reaps them after 24 hours. Explicit client.files.upload(...) omits purpose and remains reusable. Remaining small files keep the single multipart round-trip.

From a Path

from pathlib import Path

client.run("workflows.extract-invoice", input={
    "contract_document": Path("contract.pdf"),
})

Filename and MIME type are inferred automatically.

From a file handle

with open("contract.pdf", "rb") as f:
    client.run("workflows.extract-invoice", input={"contract_document": f})

Filename inferred from f.name.

From raw bytes

client.run("workflows.extract-invoice", input={
    "contract_document": {
        "content": data,
        "filename": "contract.pdf",
        "mime_type": "application/pdf",
    },
})

Multiple files

client.run("workflows.compare-versions", input={
    "original": Path("v1.pdf"),
    "revised": Path("v2.pdf"),
    "reference": Path("ref.pdf"),
})

Each file becomes a files.<fieldName> multipart part. Mix files and scalar inputs freely; scalars ride in the input JSON part automatically.

Nested files are not extracted

Only top-level file values become multipart fields. Files inside lists or nested dicts stay in the input JSON part and the server will not see them as uploads:

# DON'T — `documents` becomes a JSON list, no upload.
client.run("workflows.compare", input={"documents": [Path("a.pdf"), Path("b.pdf")]})

# DO — flatten to top-level keys, your workflow accepts them by name.
client.run("workflows.compare", input={"document_0": Path("a.pdf"), "document_1": Path("b.pdf")})

Do not base64 yourself

# Don't do this. Doubles the payload size and skips the optimised path.
import base64
client.run("workflows.extract-invoice", input={
    "contract_document": base64.b64encode(data).decode(),
})

The SDK picks multipart whenever it sees a Path, file-like object, or {"content": ..., "filename": ..., "mime_type": ...} dict. Plain strings pass through as scalar inputs.

Overview

TypeScript

Python

From a Path

From a file handle

From raw bytes

Multiple files

Nested files are not extracted

Do not base64 yourself

​From a Path

​From a file handle

​From raw bytes

​Multiple files

​Nested files are not extracted

​Do not base64 yourself

From a Path

From a file handle

From raw bytes

Multiple files

Nested files are not extracted

Do not base64 yourself