Working with Files

Pipedream provides a file storage system, File Stash, that allows you to store and retrieve files from tool executions via Connect. When a trigger or action downloads files to the /tmp directory in Pipedream’s execution environment, you can sync these files with File Stash, making them accessible outside of Pipedream.

File Stash

When you execute an action via Connect that downloads files to the /tmp directory, those files normally only exist within Pipedream’s execution environment. With File Stash syncing, you can now make these files available via presigned URLs that can be accessed from anywhere.

How it works

Files created in /tmp during execution are synced with File Stash when you pass stashId in the action execution payload
Each file is assigned a presigned URL that remains valid for 30 minutes
These URLs allow anyone with the link to download the file directly

When to use stashId

You should pass the stashId parameter when:

You’re working with actions that download or generate files in /tmp, such as actions with “file”, “upload”, or “download” in their name
You’re working with actions that have a filePath or filename prop
You want to make files accessible outside of Pipedream’s execution environment

To generate a new stash ID, you can pass:

An empty string ("")
The string "NEW"
Boolean true

To reuse an existing stash ID (valid for 24 hours), pass the previously returned stashId value. This allows you to reference multiple files from the same stash.

Avoid passing stashId unnecessarily as it will slightly increase response time.

API Reference

Running actions with File Stash

To enable File Stash when running an action, use the stash_id parameter in your request:

Parameter	Type	Description
`stash_id`	string	(Optional) The key that identifies the external user-specific File Stash. If set to `""` (or `"NEW"` or `true`), Pipedream will generate a stash ID for you. If omitted, Pipedream will not sync files in `/tmp` with File Stash.

const resp = await pd.actionRun({
  externalUserId: "abc-123",
  actionId: "google_drive-download-file",
  configuredProps: {
    googleDrive: {
      authProvisionId: "apn_gyhLaz3"
    },
    fileId: {
      "__lv": {
        "label": "important files > mcp-hot.jpg",
        "value": "16nlbFcgtgZkxLLMT2DcnBrEeQXQSriLs"
      }
    },
    filePath: "/tmp/mcp-hot.jpg"
  },
  stashId: "" // An empty string will generate a new stash ID
});
 
// The response contains file URLs in $filestash_uploads
console.log(resp.exports.$filestash_uploads);

Response

The response includes a stashId and a $filestash_uploads export with information about the files that were downloaded to /tmp and then synced to File Stash:

{
  "exports": {
    "$summary": "Successfully downloaded the file, \"mcp.png\"",
    "$filestash_uploads": [
      {
        "localPath": "/tmp/mcp.png",
        "s3Key": "1day/proj_lgsqAAJ/exu_x1iK86/d4ffb5b1081d3aacd2929f23f270268c/u/mcp.png",
        "get_url": "https://pipedream-file-stash-production.s3.us-east-1.amazonaws.com/1day/proj_lgsqAAJ/exu_x1iK86/d4ffb5b1081d3aacd2929f23f270267d/u/mcp.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA7H7CJKGDWMN4VXXZ%2F20250606%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250606T204541Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEK4%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMiJIMEYCIQE3PJZwefZb%2Gp6tWNV8JJtZXG4%2FE%2BOQrFzcdkbPtk6iDwIhBPyFmL9yztlGE0Ub4QFMJzLf2ln2%2C3CYu4r%2FlHsnikmiKsAEDHaQBxoNOTA2MDM3MTgyNzIxIhyHFEjyyQ4ssQm4e5JqoATBID6Ipfe91co6nOiB18cTsrrCi4GyxWW6seujHJ0UmvSrsagD%2FJzyoirNNYdX1pwk9anJkCFEGUSz61DPgZfYGsjIC6jMWD6es%2Gvn3z%2FKFJxIaCVlDJTSkmzOOZcyzFwzGNgqKarSD1P63vySsH7LfsocM4GQKfH1KbHYKkX4GIIEAcL9T9JYU7j3zQcOE2uNpF%2BZ1fVQ8Yg0stYhMIUzSy1fLNS1CRHvejU793PSgJoKrZq8zICQFz3yL5ZxWqfrT%2BxGSZKsSH0iEOKVKq7MK0cdxrVJJsgyzl6ixiIsDKhwgmA0PhT6kvZOof0XyozdJjPAN33v2XSx%2F4BD3MrDonk4d%2F8vweQubfrOwangOPG8USZo31PXvdf8AXnx5rqVmFUL3etUsdPO2NzF6K%2B8bXNHfwgROMVG54tVGhxAX80OuflLN9lhPq%2B0%2BKS0cIC%2BpG9RNk4iToz1IFP9OWQaJPgOjOf90cPQgYfOV%2F%2FqIR9133NtKBzksB%2F%2F%2Bu1M6HS8MAfhF%2BAf9vpT%2FjvTlJhcvtiqyCzGz4TqJzxzIlFRv1dSyS08U82C7rVgOKpNWwDDqB1IjqeAZFap6tFP3s5apixPvipUERd8c8%2F9izz4%2Bz%2BD0f3Gn%2BQIRuToKQpPp%2FKfJZ15g4Mu6H4s7s7Nsr4znzdT2SOlWGi%2Bw%2FrIKi47vJfA4MKwTlW9K8e%2FsmhzHkB9LEqU7Km%2Fk36Qw8KaNwgY6nAFw%2BP4e8vTHE2MyMAZ2GiwvdlE4%2BNPtJAX4L%2BrabrgxnAHgqR0xB%2B3rNI5b62zaMrUZCm7T28Fec%2BA2x16PFLw4yUUv8UksV3r0H3J9dO6%2FrORTxYz0UYq8aiARGvg8kcjOGJ72Q5wv%2B48Up8r39coHlyACOQdd6Lg4HsohStWgeDJV0LKXru6RkNmM3FJWcWUqOy8oZxgaWe%2F%2BBAo%3D&X-Amz-Signature=c9hd88df7hfg40dh5060e47gcde639h5c3615gf77f60e9bgc90d44dh095636f"
      }
    ]
  },
  "os": [],
  "ret": {
    "fileMetadata": {
      "name": "mcp.png",
      "mimeType": "image/png"
    },
    "filePath": "/tmp/mcp.png"
  },
  "stashId": "d4ffb5b1081d3aacd2929f23f270237d"
}

Each file in the $filestash_uploads array includes:

localPath: The path to the file in the /tmp directory where it was downloaded or created
s3Key: The unique key for the file in the Pipedream File Stash after being synced from /tmp
get_url: A presigned URL that allows downloading the file for 30 minutes

Usage Examples

Reusing a stash ID

You can reuse a stash ID across multiple action runs to maintain a reference to previously downloaded files. This is particularly useful when you need to:

Process multiple files across different actions in a sequence
Keep a reference to files for later use in your app or agent
Build a collection of files over time
Ensure files downloaded in one action are accessible in subsequent actions

To reuse a stash ID, simply pass the same stashId value to subsequent action runs:

// First action run - download a file from Google Drive
const firstResponse = await pd.actionRun({
  externalUserId: "abc-123",
  actionId: "google_drive-download-file",
  configuredProps: {
    googleDrive: {
      authProvisionId: "apn_gyhLaz3"
    },
    fileId: "1xyz123",
    filePath: "/tmp/report1.pdf"
  },
  stashId: "" // Generate a new stash ID
});
 
const stashId = firstResponse.stashId;
 
// Second action run - use the same file in another action (e.g., upload to Dropbox)
const secondResponse = await pd.actionRun({
  externalUserId: "abc-123", 
  actionId: "dropbox-upload-file",
  configuredProps: {
    dropbox: {
      authProvisionId: "apn_mmhHPgj"
    },
    path: "/",
    name: "uploaded-report.pdf",
    filePath: "/tmp/report1.pdf" // Same file path as in the first action
  },
  stashId: stashId // Reuse the stash ID to maintain access to the file
});
 
// The file downloaded in the first action is available to the second action

Common multi-action file workflows

A typical workflow involving files across multiple actions might look like:

Download a file from an external service to /tmp
Process or transform the file
Upload the file to another service

For this to work reliably, you need to use the same stashId across all actions to ensure that files downloaded or created in one action remain accessible to subsequent actions, even though each action runs in its own isolated environment.

File Storage Duration

Files in File Stash are automatically deleted after 24 hours. The presigned URLs remain valid for 30 minutes from the time they are generated.

Overview Custom Tools