File Uploads

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.

curl -X POST https://api.webrun.ai/files/upload \
  -H "Authorization: Bearer wr_xxx" \
  -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://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:

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=<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://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>"]
  }'

With /start/start-session

Include files inside the task object:

{
  "mode": "default",
  "environmentId": "<ENV_ID>",
  "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:

{
  "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 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:

# List all files in an environment
curl https://api.webrun.ai/environments/<ENV_ID>/files \
  -H "Authorization: Bearer wr_xxx"

# Delete a specific file
curl -X DELETE https://api.webrun.ai/environments/<ENV_ID>/files/<FILE_ID> \
  -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/<ENV_ID>/files`	—	List files in an environment
`DELETE /environments/<ENV_ID>/files/<FILE_ID>`	—	Delete a file from an environment

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Upload to an Environment (Persistent)

Upload Without an Environment (Orphan)

Upload Response Fields

Uploading Multiple Files

Using Files in a Session

With /start/run-task

With /start/start-session

With /start/send-message

Complete Example

Managing Environment Files

Endpoint Reference

​Upload to an Environment (Persistent)

​Upload Without an Environment (Orphan)

​Upload Response Fields

​Uploading Multiple Files

​Using Files in a Session

​With /start/run-task

​With /start/start-session

​With /start/send-message

​Complete Example

​Managing Environment Files

​Endpoint Reference

Environments API

Environments Overview

Secrets

Webhooks

Upload to an Environment (Persistent)

Upload Without an Environment (Orphan)

Upload Response Fields

Uploading Multiple Files

Using Files in a Session

With /start/run-task

With /start/start-session

With /start/send-message

Complete Example

Managing Environment Files

Endpoint Reference