> 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 provides standard way to receive, securely store, and reuse files across workflow modules.

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="https://3389950191-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO4RFXIz4V8iqghJ3JVSs%2Fuploads%2FtsoeOUi6nfkjaKBFvdZ5%2Fimage.png?alt=media&amp;token=51ed44fe-c918-4043-9d94-1a96dfc79236" 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="https://3389950191-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO4RFXIz4V8iqghJ3JVSs%2Fuploads%2F01TrxiBZ7lLB6vFomznO%2Fimage.png?alt=media&amp;token=276a9c8e-17cf-4a80-8a54-1c020c667877" 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**.