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.
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:
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
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": "<ENV_ID>", "files": ["<FILE_ID>"] }'
Include files in the message object when sending a newTask action:
{ "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:
const API_KEY = process.env.WEBRUN_API_KEY;const ENV_ID = "<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 automaticallyconst 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:
# List all files in an environmentcurl https://api.webrun.ai/environments/<ENV_ID>/files \ -H "Authorization: Bearer wr_xxx"# Delete a specific filecurl -X DELETE https://api.webrun.ai/environments/<ENV_ID>/files/<FILE_ID> \ -H "Authorization: Bearer wr_xxx"