|
| 1 | +import { Tabs } from "nextra/components"; |
| 2 | +import Callout from '@/components/Callout'; |
| 3 | + |
| 4 | +# Working with Files |
| 5 | + |
| 6 | +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. |
| 7 | + |
| 8 | +## File Stash |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +### How it works |
| 13 | + |
| 14 | +1. Files created in `/tmp` during execution are synced with a Pipedream File Store when you pass `stashId` in the action execution payload |
| 15 | +2. Each file is assigned a presigned URL that remains valid for 30 minutes |
| 16 | +3. These URLs allow anyone with the link to download the file directly |
| 17 | + |
| 18 | +## When to use stashId |
| 19 | + |
| 20 | +You should pass the `stashId` parameter when: |
| 21 | + |
| 22 | +1. You're working with actions that download or generate files in `/tmp`, such as actions with "file", "upload", or "download" in their name |
| 23 | +2. You're working with actions that have a `filePath` or `filename` prop |
| 24 | +3. You want to make files accessible outside of Pipedream's execution environment |
| 25 | + |
| 26 | +To generate a new stash ID, you can pass: |
| 27 | +- An empty string (`""`) |
| 28 | +- The string `"NEW"` |
| 29 | +- Boolean `true` |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +<Callout type="info"> |
| 34 | +Avoid passing `stashId` unnecessarily as it will slightly increase response time. |
| 35 | +</Callout> |
| 36 | + |
| 37 | +## API Reference |
| 38 | + |
| 39 | +### Running actions with File Stash |
| 40 | + |
| 41 | +To enable File Stash when running an action, use the `stash_id` parameter in your request: |
| 42 | + |
| 43 | +| Parameter | Type | Description | |
| 44 | +| --- | --- | --- | |
| 45 | +| `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. | |
| 46 | + |
| 47 | +<Tabs items={['Node.js', 'HTTP (cURL)']}> |
| 48 | +<Tabs.Tab> |
| 49 | +```javascript |
| 50 | +const resp = await pd.actionRun({ |
| 51 | + externalUserId: "abc-123", |
| 52 | + actionId: "google_drive-download-file", |
| 53 | + configuredProps: { |
| 54 | + googleDrive: { |
| 55 | + authProvisionId: "apn_gyhLaz3" |
| 56 | + }, |
| 57 | + fileId: { |
| 58 | + "__lv": { |
| 59 | + "label": "important files > mcp-hot.jpg", |
| 60 | + "value": "16nlbFcgtgZkxLLMT2DcnBrEeQXQSriLs" |
| 61 | + } |
| 62 | + }, |
| 63 | + filePath: "/tmp/mcp-hot.jpg" |
| 64 | + }, |
| 65 | + stashId: "" // An empty string will generate a new stash ID |
| 66 | +}); |
| 67 | + |
| 68 | +// The response contains file URLs in $filestash_uploads |
| 69 | +console.log(resp.exports.$filestash_uploads); |
| 70 | +``` |
| 71 | +</Tabs.Tab> |
| 72 | +<Tabs.Tab> |
| 73 | +```bash |
| 74 | +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \ |
| 75 | + -H "Content-Type: application/json" \ |
| 76 | + -H "X-PD-Environment: {environment}" \ |
| 77 | + -H "Authorization: Bearer {access_token}" \ |
| 78 | + -d '{ |
| 79 | + "external_user_id": "abc-123", |
| 80 | + "id": "google_drive-download-file", |
| 81 | + "configured_props": { |
| 82 | + "googleDrive": { |
| 83 | + "authProvisionId": "apn_jyhKbx4" |
| 84 | + }, |
| 85 | + "fileId": { |
| 86 | + "__lv": { |
| 87 | + "label": "important files > mcp-hot.jpg", |
| 88 | + "value": "16nlbFcgtgZkxLLMT2DcnBrEeQXQSriLw" |
| 89 | + } |
| 90 | + }, |
| 91 | + "filePath": "/tmp/mcp.png" |
| 92 | + }, |
| 93 | + "stash_id": "" |
| 94 | + }' |
| 95 | +``` |
| 96 | +</Tabs.Tab> |
| 97 | +</Tabs> |
| 98 | + |
| 99 | +### Response |
| 100 | + |
| 101 | +The response includes a `stashId` and a `$filestash_uploads` export with information about the uploaded files: |
| 102 | + |
| 103 | +```json |
| 104 | +{ |
| 105 | + "exports": { |
| 106 | + "$summary": "Successfully downloaded the file, \"mcp.png\"", |
| 107 | + "$filestash_uploads": [ |
| 108 | + { |
| 109 | + "localPath": "/tmp/mcp.png", |
| 110 | + "s3Key": "1day/proj_lgsqAAJ/exu_x1iK86/d4ffb5b1081d3aacd2929f23f270268c/u/mcp.png", |
| 111 | + "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=ASIA5F5AGIEAUKI2SRTS%2F20250606%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250606T204541Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luY3VjEI3%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD2OIYvdeYa%2Fo5sVMU7IIsYWF3%2FD%2BNQqEybkjaOsj5hCwIhAOxElK8xyskFD9Ta3PELIyKe1km1%2B2BXt3q%2FkGrmhjkhKr8ECGYQAxoMOTA2MDM3MTgyNzIxIgyGEDixxP3rrPl3d4IqnATAHC5Hoed80bn5mNhA07bRrqqBh3FxkWV5rdtiGI9TluRqrZfC%2FIzxnhqMMXcW0ovj8ZmIjBEDFTQRy50COfYeXFriHB5iLVC5dr%2FumYt2y%2FJEIwIaCVlDJTSkmzOOZcyzFwzGNgqKarSD1P63vySsH7LfsocM4GQKfH1KbHYKkX4GIIEAcL9T9JYU7j3zQcOE2uNpF%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=a7fb66bdf5de28bf3848c25eacbc417e3a1493ed55d38a7eb68b22bef873413d" |
| 112 | + } |
| 113 | + ] |
| 114 | + }, |
| 115 | + "os": [], |
| 116 | + "ret": { |
| 117 | + "fileMetadata": { |
| 118 | + "name": "mcp.png", |
| 119 | + "mimeType": "image/png" |
| 120 | + }, |
| 121 | + "filePath": "/tmp/mcp.png" |
| 122 | + }, |
| 123 | + "stashId": "d4ffb5b1081d3aacd2929f23f270237d" |
| 124 | +} |
| 125 | +``` |
| 126 | + |
| 127 | +Each file in the `$filestash_uploads` array includes: |
| 128 | + |
| 129 | +- `localPath`: The path to the file in the `/tmp` directory |
| 130 | +- `s3Key`: The unique key for the file in the Pipedream File Store |
| 131 | +- `get_url`: A presigned URL that allows downloading the file for 30 minutes |
| 132 | + |
| 133 | +## Usage Examples |
| 134 | + |
| 135 | +### Reusing a stash ID |
| 136 | + |
| 137 | +To add more files to an existing stash, provide the same `stash_id` in subsequent action runs: |
| 138 | + |
| 139 | +<Tabs items={['Node.js', 'HTTP (cURL)']}> |
| 140 | +<Tabs.Tab> |
| 141 | +```javascript |
| 142 | +// First run generates a stash ID |
| 143 | +const firstRun = await pd.actionRun({ |
| 144 | + externalUserId: "abc-123", |
| 145 | + actionId: "download-file-1", |
| 146 | + configuredProps: { /* ... */ }, |
| 147 | + stashId: "NEW" |
| 148 | +}); |
| 149 | + |
| 150 | +// Save the stash ID |
| 151 | +const savedStashId = firstRun.stashId; |
| 152 | + |
| 153 | +// Later, add more files to the same stash |
| 154 | +const secondRun = await pd.actionRun({ |
| 155 | + externalUserId: "abc-123", |
| 156 | + actionId: "download-file-2", |
| 157 | + configuredProps: { /* ... */ }, |
| 158 | + stashId: savedStashId // Reuse the existing stash ID |
| 159 | +}); |
| 160 | +``` |
| 161 | +</Tabs.Tab> |
| 162 | +<Tabs.Tab> |
| 163 | +```bash |
| 164 | +# First request with new stash |
| 165 | +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \ |
| 166 | + -H "Content-Type: application/json" \ |
| 167 | + -H "Authorization: Bearer {access_token}" \ |
| 168 | + -d '{ |
| 169 | + "external_user_id": "abc-123", |
| 170 | + "id": "download-file-1", |
| 171 | + "configured_props": { /* ... */ }, |
| 172 | + "stash_id": "NEW" |
| 173 | + }' |
| 174 | + |
| 175 | +# Get the stash_id from the response |
| 176 | + |
| 177 | +# Second request using the same stash |
| 178 | +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \ |
| 179 | + -H "Content-Type: application/json" \ |
| 180 | + -H "Authorization: Bearer {access_token}" \ |
| 181 | + -d '{ |
| 182 | + "external_user_id": "abc-123", |
| 183 | + "id": "download-file-2", |
| 184 | + "configured_props": { /* ... */ }, |
| 185 | + "stash_id": "d4ffb5b1081d3aacd2929f23f270237d" |
| 186 | + }' |
| 187 | +``` |
| 188 | +</Tabs.Tab> |
| 189 | +</Tabs> |
| 190 | + |
| 191 | +## File Storage Duration |
| 192 | + |
| 193 | +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. |
0 commit comments