# 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="https://3389950191-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO4RFXIz4V8iqghJ3JVSs%2Fuploads%2FtsoeOUi6nfkjaKBFvdZ5%2Fimage.png?alt=media&#x26;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&#x26;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.