# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacksync.com/workflow-automation/features/stacksync-file-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.