Files

Builder is the full-code door onto the foundation, and everything you build there, agents, automations, and front-ends, shares the same workspace storage. The Files tab in the Builder sidebar lists every file uploaded to the current workspace. It is the workspace-level equivalent of object storage: files sit next to (but separate from) the page source tree, automations, and apps. Use Files for runtime assets: PDFs ingested by automations, user-uploaded images, exports produced by a workflow, evidence stored for audit. For React source files that ship with a page, stay in the page editor; for app code, stay in Imports → Custom Code.

What you see

Column	Content
Icon	Type icon derived from the file’s MIME type (image, PDF, Word, spreadsheet, archive, audio, video, code, generic).
Filename	The original filename at upload time.
Size	Human-readable size.
Date	Upload timestamp.
Type badge	Color-coded label (`Image`, `PDF`, `Word`, `Excel`, etc.).
Open (external-link icon)	Opens the file in a new tab using its signed URL.
Download (download icon)	Downloads the file under its original name.
Delete (trash icon, double-click to confirm)	Calls `DELETE /workspaces/{id}/files/{fileId}` and removes the file from the list.

The header has a Refresh button that re-fetches the current page from the API, and a pagination control (Previous / Next) when the workspace has more files than fit in one page.

How files get there

The Files tab lists files and lets you upload them directly with the Import a file button. Files also appear there after being uploaded from an automation, a page, or the API:

From the Files tab

Click Import a file at the top of the Files tab and pick a file from your machine. It uploads to the current workspace’s storage and appears in the list immediately — the quickest way to add a runtime asset without writing an automation.

From an automation

Use a fetch instruction with multipart/form-data against the workspace files endpoint. The platform stores the file and returns its metadata (id, URL, mimetype, size).

- fetch:
    url: "{{$workspaceUrl}}/files"
    method: POST
    headers:
      Content-Type: multipart/form-data
    body:
      file:
        filename: report.pdf
        content: "{{generatedPdf}}"
    output: uploadedFile
- emit:
    event: report.uploaded
    payload:
      fileId: "{{uploadedFile.id}}"
      url: "{{uploadedFile.url}}"

The trigger for the upload is typically a webhook receiving a multipart/form-data request from a page or external system; see Triggers → URL for the request-body shape exposed to the automation.

From a page

A page can post directly to the workspace files endpoint using the injected SDK.

async function upload(sdk: SDK, workspaceId: string, file: File) {
  const form = new FormData()
  form.append("file", file)

  const response = await fetch(
    `${sdk.host}/workspaces/${workspaceId}/files`,
    {
      method: "POST",
      headers: {
        ...(sdk.token ? { Authorization: `Bearer ${sdk.token}` } : {}),
      },
      body: form,
    }
  )

  return response.json()
}

From the API directly

POST /v2/workspaces/{id}/files with a multipart/form-data body. The endpoint is documented in the Platform API reference.

File URLs

Each file is served from a signed URL stored on the file record. The URL is what the Open and Download buttons use; it is also what uploadedFile.url returns to automations and pages. URLs are signed for the workspace’s storage provider (S3-compatible by default in self-hosted deployments). They expire; re-fetch the file metadata if you need a fresh URL.

Restore a deleted file

If the workspace storage backend has object versioning enabled (S3/GCS bucket versioning, or Azure blob soft‑delete), a deleted file can be brought back from the API: POST /v2/workspaces/{id}/files/restore

{
  "paths": ["<workspaceId>/<fileId>.<filename>"],
  "expiresAfter": 3600,
  "metadata": { "restoredBy": "ops" }
}

paths — one or more storage object keys to restore. Bulk restore is supported by passing several keys. A single path string is also accepted.
expiresAfter (optional) — expiration in seconds, applied to every restored file.
metadata (optional) — arbitrary JSON attached to every restored file.

The default object key embeds both the id and the name (<workspaceId>/<id>.<filename>), so the file record is reconstructed from the key. The endpoint restores the object in the bucket and recreates its database entry. If the database entry still exists but the object was removed from the bucket, the object is restored and the entry’s metadata/expiresAfter are updated in place. Restoring a file that is still present is a no‑op that simply returns its metadata. Restore requires the storage backend to have versioning turned on — it is an infrastructure setting, not a workspace one. Without it, there is no prior version to recover and the call returns 404.

What’s not in Files

Asset	Where it lives instead
Page source files (`src/App.tsx`, `package.json`, …)	Pages tab. They are part of the workspace bundle, not its file storage.
Custom Code source	Imports → Custom Code.
App configuration	Imports → `<app>` → Configure.
Secrets	Settings → Secrets.
Crawled documents and embeddings	Stored by the respective app (AI Knowledge, etc.), not in the workspace file list.

Lifecycle

Files are not included in workspace exports or pushes to Git; versioning saves the static configuration but not runtime data. See Versioning → What’s Versioned.
Deleting a file is immediate from the UI. It can be undone with POST /v2/workspaces/{id}/files/restore only when the storage backend has object versioning enabled (see Restore a deleted file); otherwise it is irreversible. If you need guaranteed history, archive the file in your own storage before deleting.
Per-file size limits and total quota are controlled by the platform deployment (see Self-Hosting → Configuration → Upload and request limits).

Troubleshooting

My uploaded file does not appear in the list

Click Refresh; the list shows the current page only and does not auto-update on every upload. If the file is still missing, check the workspace Activity for a workspaces.files.error event, which contains the underlying storage error.

The file URL returns 403 or 410

Signed URLs expire. Re-fetch the file metadata (GET /v2/workspaces/{id}/files/{fileId}) to obtain a fresh URL, or rebuild the URL from a fresh uploadedFile payload returned by your automation.

Uploads fail from a page

The page must include the platform’s CSRF token in the request headers if the user is authenticated. See the SDK reference for the helper that injects it automatically.

I cannot delete a file

Deletion requires the ManageWorkspace ability. Check your role in Settings → Sharing or with the workspace owner.

Overview

Chat

Agent Creator

Knowledges

Collections

Builder

Governe

Engage

Insights

What you see

How files get there

From the Files tab

From an automation

From a page

From the API directly

File URLs

Restore a deleted file

What’s not in Files

Lifecycle

Troubleshooting

Next steps

Automations

Pages

​What you see

​How files get there

​From the Files tab

​From an automation

​From a page

​From the API directly

​File URLs

​Restore a deleted file

​What’s not in Files

​Lifecycle

​Troubleshooting

​Next steps

Automations

Pages

What you see

How files get there

From the Files tab

From an automation

From a page

From the API directly

File URLs

Restore a deleted file

What’s not in Files

Lifecycle

Troubleshooting

Next steps