> ## Documentation Index > Fetch the complete documentation index at: https://docs.webrun.ai/llms.txt > Use this file to discover all available pages before exploring further. # File Uploads > Upload files to environments for persistent access, or upload standalone files for temporary use When your agent needs to work with files (submitting a PDF to a form, importing a spreadsheet, or uploading an image) you upload them first and then reference them by `fileId` in your tasks. Files can be uploaded in two modes: | Mode | Behavior | | - | - | | **Persistent** | Attached to an environment. Available to any session on that environment. Only deleted when you explicitly remove them. | | **Orphan** | No environment attached. Automatically deleted after **1 hour**. Can be promoted to an environment later. | *** ## Upload to an Environment (Persistent) Include `environmentId` in the form data to attach the file permanently to an environment. Any session using that environment can access the file at any time. ```bash theme={null} curl -X POST https://api.webrun.ai/files/upload \ -H "Authorization: Bearer wr_xxx" \ -F "files=@/path/to/sample.zip" \ -F "environmentId=" ``` **Response:** ```json theme={null} { "success": true, "files": [ { "fileId": "abc123...", "originalName": "sample.zip", "size": 204800 } ] } ``` *** ## Upload Without an Environment (Orphan) Omit `environmentId` to upload a standalone file. It is automatically deleted after 1 hour unless promoted to an environment. ```bash theme={null} curl -X POST https://api.webrun.ai/files/upload \ -H "Authorization: Bearer wr_xxx" \ -F "files=@/path/to/sample.zip" ``` An orphan file is automatically promoted to an environment when you pass its `fileId` in a session or task that also includes an `environmentId`. Once the session runs, the file is persisted to that environment and won't expire. *** ## Upload Response Fields | Field | Type | Description | | - | - | - | | `success` | boolean | Whether the upload succeeded | | `files` | array | Array of uploaded file metadata | | `files[].fileId` | string | Unique identifier: use this to reference the file in tasks | | `files[].originalName` | string | Original filename as uploaded | | `files[].size` | number | File size in bytes | *** ## Uploading Multiple Files Repeat the `files` field to upload several files in one request: ```bash theme={null} curl -X POST https://api.webrun.ai/files/upload \ -H "Authorization: Bearer wr_xxx" \ -F "files=@document.pdf" \ -F "files=@photo.png" \ -F "files=@spreadsheet.xlsx" \ -F "environmentId=" ``` *** ## Using Files in a Session Reference uploaded files by `fileId` when starting a task. Pass them in the `files` array alongside `environmentId` to use the environment's browser profile and persist orphan files at the same time. ### With /start/run-task ```bash theme={null} curl -X POST https://api.webrun.ai/start/run-task \ -H "Authorization: Bearer wr_xxx" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Open the uploaded spreadsheet and extract the data", "environmentId": "", "files": [""] }' ``` ### With /start/start-session Include `files` inside the `task` object: ```json theme={null} { "mode": "default", "environmentId": "", "task": { "prompt": "Process the attached report", "startingUrl": "https://example.com/dashboard", "files": ["abc123..."] } } ``` ### With /start/send-message Include `files` in the `message` object when sending a `newTask` action: ```json theme={null} { "sessionId": "a1b2c3d4e5f6", "message": { "actionType": "newTask", "newState": "start", "prompt": "Upload the attached spreadsheet to the data import page", "startingUrl": "https://example.com/import", "files": ["ghi789..."] } } ``` *** ## Complete Example Upload an orphan file, then run a task with an environment; the file gets persisted automatically: ```javascript theme={null} const API_KEY = process.env.WEBRUN_API_KEY; const ENV_ID = ""; // Step 1: Upload the file (orphan, no environmentId yet) const formData = new FormData(); formData.append("files", fs.createReadStream("report.pdf")); const uploadResponse = await fetch("https://api.webrun.ai/files/upload", { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}` }, body: formData }).then(r => r.json()); const fileId = uploadResponse.files[0].fileId; // Step 2: Run a task with the environment and file // The orphan file is promoted to the environment automatically const taskResponse = await fetch("https://api.webrun.ai/start/run-task", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${API_KEY}` }, body: JSON.stringify({ prompt: "Go to the upload page and submit the attached PDF report", startingUrl: "https://example.com/submit", environmentId: ENV_ID, files: [fileId] }) }).then(r => r.json()); console.log(taskResponse); ``` *** ## Managing Environment Files List or delete files attached to an environment using the [Environments API](/environments/environments-api): ```bash theme={null} # List all files in an environment curl https://api.webrun.ai/environments//files \ -H "Authorization: Bearer wr_xxx" # Delete a specific file curl -X DELETE https://api.webrun.ai/environments//files/ \ -H "Authorization: Bearer wr_xxx" ``` *** ## Endpoint Reference | Endpoint | Field | Location | | - | - | - | | `POST /files/upload` | `files` (multipart) | Form data | | `POST /files/upload` | `environmentId` | Form data (optional: omit for orphan upload) | | `POST /start/run-task` | `files` | Request body | | `POST /start/run-task` | `environmentId` | Request body | | `POST /start/start-session` | `files` | Inside `task` object | | `POST /start/send-message` | `files` | Inside `message` object | | `GET /environments//files` | — | List files in an environment | | `DELETE /environments//files/` | — | Delete a file from an environment | *** Create environments and manage attached files What environments are and when to use them Provide credentials for authenticated sessions Get notified when tasks complete This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.