Uploads & storage

Choose a storage provider

The decision is whose bucket the bytes land in, and you do not have to make it before the first form goes live. A newly provisioned workspace can take an upload form live before storage setup: files use Fillo's private transit bucket for up to seven days, capped at 10 MiB per file and 100 MiB per workspace. Connect storage once at the workspace level for durable collection, then choose a destination per form. In both modes the browser sends bytes directly to the bucket/provider while Fillo verifies completion and keeps the response-safe reference.

Prepare an S3 or R2 bucket for recoverable deletion

Fillo accepts an S3-compatible connection only after it proves the permissions and provider behavior needed for browser-direct multipart uploads, crash recovery, and permanent file deletion. The same erasure capability is checked again before respondent bytes are accepted or materialized.

• Use a network-reachable HTTPS endpoint and keep the bucket private. For ordinary S3, scope credentials to the fillo/ prefix with object read, write, and delete; multipart create, list, and abort; bucket-version listing; and lifecycle-read permissions.
• Allow browser PUT requests from every hosted or embedded form origin in the bucket CORS policy.
• For AWS S3, use a bucket that has never had Versioning enabled. Enabled and suspended versioning are rejected. MFA Delete and Object Lock must also be off because they can prevent immediate erasure.
• Cloudflare R2 does not implement object versioning. Use its official <ACCOUNT_ID>.r2.cloudflarestorage.com S3 endpoint with auto region and bucket-scoped Object Read & Write credentials. Fillo relies on R2's guaranteed seven-day expiry for incomplete multipart uploads and does not require bucket-configuration access.
• For non-R2 S3, add an enabled AbortIncompleteMultipartUpload lifecycle rule covering fillo/ with 7 days or fewer.
• Connection verification creates an empty multipart upload, proves it can be rediscovered and aborted, then creates empty sentinel objects and proves permanent deletion. It never uploads respondent content during the check.

Connect, assign, and publish

1. 1

   Connect the provider

   Open Settings → Connections, or stay in the terminal: fillo storage connect s3 takes bucket credentials headlessly, and fillo storage connect drive|box prints the provider's consent URL and waits for the connection. Keep OAuth grants and bucket credentials limited to the workspace that needs them.

2. 2

   Assign it to the form

   Open the form's Settings → File storage and select the destination. A connection can serve several forms, but each form chooses its own active provider.

3. 3

   Add file fields and publish

   Use the builder or a code-defined file_upload field (<Fillo.FileUpload> in JSX). An eligible provisioned workspace uses capped transit storage when no customer provider is connected, so the first code-defined upload form can go live immediately. Outside that temporary lane, publishing requires a connected destination.

4. 4

   Test the real path

   Submit a representative file from the hosted form or embed, confirm it appears in the provider, then open it from the response drawer as a workspace member.

What happens during an upload

• The SDK asks Fillo for an upload session bound to the form, field, provider, filename, MIME type, and expected size.
• The browser transfers bytes to the private transit bucket, Drive, S3/R2, or Box. Provider credentials and OAuth refresh tokens stay server-side; the browser receives only the scoped capability needed for that upload.
• The SDK reports completion to Fillo. The storage adapter verifies the provider result before the file reference can be submitted with the response.
• The response stores file metadata and a provider reference, not a public provider credential. Durable files require signed-in workspace access. While a workspace is still unclaimed, its browser claim may open only that workspace's short-lived transit files.
• Transit downloads redirect an authorized workspace viewer (a member or the live provisional browser claim) to a two-minute attachment-only signed URL on the storage host. After seven days the bytes are erased and the response keeps an expired-file tombstone.

Custom upload UI and resume handles

The default React and DOM renderers already run the upload protocol. If your headless screen owns the file picker, call client.uploadFile() and store the returned file value in the form answer.

For reload-safe recovery, persist the sessionId and uploadToken supplied to onSession, then pass them back with the same file. Resume behavior follows the provider protocol; do not reuse a handle for a different file or field.

const fileValue = await client.uploadFile(formId, file, {
  fieldId: "attachment",
  onProgress: ({ fraction }) => setProgress(fraction),
  onSession: ({ sessionId, uploadToken }) => {
    saveResumeHandle({ sessionId, uploadToken });
  },
});

Switch or disconnect storage

Changing a form's destination affects new upload sessions. Existing responses keep references to the provider that accepted their files, so switching providers does not migrate historical objects.

• Let active uploads finish or ask respondents to restart after the change; completion rejects a session if the form's storage changed mid-upload.
• Unpublish a live form with file fields before removing its destination, or choose another connected destination in the same settings panel.
• Keep the old provider connection while historical files still need to open or be erased. If access is revoked externally, reconnect the same account or bucket before attempting cleanup.
• Provider lifecycle rules are yours. For S3/R2, retain Fillo's object prefix and incomplete-multipart cleanup requirements when changing bucket policy.

Troubleshoot uploads

Next steps