Working with Files
Pipedream provides a file storage system 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 a Pipedream File Store, 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 a Pipedream File Store when you passstashId
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
orfilename
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 createds3Key
: The unique key for the file in the Pipedream File Store 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 the File Stash are automatically deleted after 24 hours. The presigned URLs remain valid for 30 minutes from the time they are generated.