> ## Documentation Index > Fetch the complete documentation index at: https://pipedream.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. If you have any feedback on File Stash, please let us know in our [community](https://pipedream.com/support). ## 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 1. Files created in `/tmp` during execution are synced with File Stash when you pass `stashId` in the action execution payload 2. Each file is assigned a presigned URL that remains valid for 30 minutes 3. These URLs allow anyone with the link to download the file directly ## Identifying file props Props with `format` set to `”file-ref”` accept both a URL of a file and a path to a file in `/tmp`. You can use this property to reliably identify file-related props. Some file-related props may not have `format: “file-ref”` set. These props may accept a file URL or a `/tmp` path (but not necessarily both). When `format` is not present, you can fall back to the heuristics in the [When to use stashId](#when-to-use-stashid) section below. The `format` field is returned in the prop definition from the [Retrieve component](/connect/api-reference/retrieve-component) or [List components](/connect/api-reference/list-components) endpoint: ```json theme={null} { "name": "file", "type": "string", "label": "File", "description": "The URL of a file or the path to a file in the `/tmp` directory", "format": "file-ref" } ``` ## When to use stashId You should pass the `stashId` parameter when the component’s `stash` attribute indicates that a `stashId` is `"required"` or `"optional"`. You can find the `stash` indicator in the response from the [Retrieve component](/connect/api-reference/retrieve-component) or [List components](/connect/api-reference/list-components) endpoint. Typically, if `stash` is `"required"`, then the component outputs a file to `/tmp`. If `stash` is `"optional"`, then the component may accept as input either a local file path, in which case `stashId` is required, or a remote file URL, in which case `stashId` can be omitted. You can also use these heuristics to determine when to use `stashId`: 1. You’re working with actions that download or generate files in `/tmp`, such as actions with “file”, “upload”, or “download” in their name 2. You’re working with actions that have a prop with `format` set to `"file-ref"`, or a `filePath`, `filename`, or `file` prop 3. 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. | ```js Node.js theme={null} const resp = await client.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); ``` ```sh HTTP (cURL) theme={null} curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \ -H "Content-Type: application/json" \ -H "X-PD-Environment: {environment}" \ -H "Authorization: Bearer {access_token}" \ -d '{ "external_user_id": "abc-123", "id": "google_drive-download-file", "configured_props": { "googleDrive": { "authProvisionId": "apn_jyhKbx4" }, "fileId": { "__lv": { "label": "important files > mcp-hot.jpg", "value": "16nlbFcgtgZkxLLMT2DcnBrEeQXQSriLw" } }, "filePath": "/tmp/mcp.png" }, "stash_id": "" }' ``` ### 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: ```json theme={null} { "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: ```js Node.js theme={null} // First action run - download a file from Google Drive const firstResponse = await client.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 client.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 ``` ```sh HTTP (cURL) theme={null} # First request with new stash curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "external_user_id": "abc-123", "id": "google_drive-download-file", "configured_props": { "googleDrive": { "authProvisionId": "apn_gyhLaz3" }, "fileId": "1W6ZssXLvVE-YN8rRbQlqggCpdIF-gdh1", "filePath": "/tmp/myfile.txt" }, "stash_id": "NEW" }' # Get the stash_id from the response (e.g., "abcd1234") # Second request using the same stash curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "external_user_id": "abc-123", "id": "dropbox-upload-file", "configured_props": { "dropbox": { "authProvisionId": "apn_mmhHPgj" }, "path": "/", "name": "my-upload.txt", "filePath": "/tmp/myfile.txt" }, "stash_id": "abcd1234" }' ``` ### Common multi-action file workflows A typical workflow involving files across multiple actions might look like: 1. Download a file from an external service to `/tmp` 2. Process or transform the file 3. 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.