Skip to main content
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:
ModeBehavior
PersistentAttached to an environment. Available to any session on that environment. Only deleted when you explicitly remove them.
OrphanNo 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. 
curl -X POST https://connect.webrun.ai/files/upload \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \
  -F "files=@/path/to/sample.zip" \
  -F "environmentId=<ENV_ID>"
Response: 
{
  "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. 
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

FieldTypeDescription
successbooleanWhether the upload succeeded
filesarrayArray of uploaded file metadata
files[].fileIdstringUnique identifier — use this to reference the file in tasks
files[].originalNamestringOriginal filename as uploaded
files[].sizenumberFile size in bytes

​
Uploading Multiple Files

Repeat the files field to upload several files in one request: 
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=<ENV_ID>"

​
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

curl -X POST https://connect.webrun.ai/start/run-task \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \
  -H "Content-Type: application/json" \
  -d '{
    "taskDetails": "Open the uploaded spreadsheet and extract the data",
    "environmentId": "<ENV_ID>",
    "files": ["<FILE_ID>"]
  }'

​
With /start/start-session

Include files inside the initialTask object: 
{
  "mode": "default",
  "environmentId": "<ENV_ID>",
  "initialTask": {
    "taskDetails": "Process the attached report",
    "startingPoint": "https://example.com/dashboard",
    "files": ["abc123..."]
  }
}

​
With /start/send-message

Include files in the message object when sending a newTask action: 
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "newTask",
    "newState": "start",
    "taskDetails": "Upload the attached spreadsheet to the data import page",
    "startingPoint": "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://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({
    taskDetails: "Go to the upload page and submit the attached PDF report",
    startingPoint: "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 environment
curl https://connect.webrun.ai/environments/<ENV_ID>/files \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6"

# Delete a specific file
curl -X DELETE https://connect.webrun.ai/environments/<ENV_ID>/files/<FILE_ID> \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6"

​
Endpoint Reference

EndpointFieldLocation
POST /files/uploadfiles (multipart)Form data
POST /files/uploadenvironmentIdForm data (optional — omit for orphan upload)
POST /start/run-taskfilesRequest body
POST /start/run-taskenvironmentIdRequest body
POST /start/start-sessionfilesInside initialTask object
POST /start/send-messagefilesInside message object
GET /environments/<ENV_ID>/files—List files in an environment
DELETE /environments/<ENV_ID>/files/<FILE_ID>—Delete a file from an environment