> For the complete documentation index, see [llms.txt](https://docs.stacksync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacksync.com/agentic-workflows/features/stacksync-file-system.md).

# Stacksync File System

Stacksync File System is the platform capability for file ingestion in workflows. Files sent to workflow triggers are stored by Stacksync and represented as reusable `file_id` references. This removes raw file payload handling from downstream execution and provides a consistent integration model across workflow modules.

{% hint style="info" %}
Files are workspace scoped and can be reused across workflows in the same workspace.
{% endhint %}

#### 1. **Processing Flow**

When a POST Trigger webhook request includes file input, Stacksync automatically:

1. Ingests the incoming file payload.
2. Stores the file in Stacksync-managed storage.
3. Replaces file content with a Stacksync-managed file object containing the `file_id` reference.
4. Passes the updated payload to downstream workflow steps.

Supports both multipart file uploads and JSON payloads with embedded base64 file content.

#### 2. **Usage**

Get the POST Trigger URL from your workflow trigger configuration:

```http
https://.api.workflows.stacksync.com/workspaces/<workspace_id>/workflows/<workflow_id>:latest_draft/triggers/post_trigger/run 
```

<figure><img src="/files/IwBeThPOHgC1nPlzDEhC" alt=""><figcaption></figcaption></figure>

#### Format 1: Multipart Upload

**HTTPS Request:**

```http
curl --request 'POST' \
  --url 'https://<region>.api.workflows.stacksync.com/workspaces/<workspace_ID>/workflows/<workflow_ID>:latest_draft/triggers/post_trigger/run' \
  --form 'file=@/absolute/path/to/invoice.pdf;type=application/pdf'

```

**Transformed payload in workflow execution Trigger Output:**

```json
{
  "body": {
    "files": [
      {
        "file_id": "72ef30a9-ea74-41b2-96da-a0643c6d5d4c",
        "name": "invoice.pdf",
        "mime_type": "application/pdf",
        "pointer": "file"
      }
    ]
  }
}
```

<figure><img src="/files/c5LYy56YBIMN7AGQ3mVz" alt=""><figcaption></figcaption></figure>

#### Format 2: JSON with base64 file

**HTTPS Request:**

```http
curl --request 'POST' \
  --url 'https://<region>.api.workflows.stacksync.com/workspaces/<workspace_ID>/workflows/<Workflow>:latest_draft/triggers/post_trigger/run' \
  --header 'Content-Type: application/json' \
  --data '{
    "attachments": [
      {
        "file": {
          "name": "invoice.pdf",
          "contentType": "application/pdf",
          "contentBytes": "JVBERi0xLjQKJc..."
        }
      }
    ]
  }'
```

**Transformed payload in workflow execution Trigger Output:**

```json
{
  "body": {
    "attachments": [
      {
        "file": {
          "name": "invoice.pdf",
          "contentType": "application/pdf",
          "file_id": "72ef30a9-ea74-41b2-96da-a0643c6d5d4c",
          "pointer": "attachments[0].file"
        }
      }
    ]
  }
}
```

#### Supported Usage Pattern

1. Send files once through trigger ingestion
2. Use file\_id in downstream workflow modules
3. Reuse the same file across multiple workflow steps without re-uploading

If you have any questions or run into any blockers, reach out anytime at <hello@stacksync.com> and the Stacksync team will be happy to help.

> **Note:** The maximum supported file size is **20MB**.