> ## 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://connect.webrun.ai/files/upload \ -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \ -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://connect.webrun.ai/files/upload \ -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \ -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://connect.webrun.ai/files/upload \ -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \ -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://connect.webrun.ai/start/run-task \ -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \ -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://connect.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://connect.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://connect.webrun.ai/environments//files \ -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" # Delete a specific file curl -X DELETE https://connect.webrun.ai/environments//files/ \ -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" ``` *** ## 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