Environments API

Manage environments programmatically. These endpoints let you create and delete environments, upload browser profile data, and manage files attached to an environment.

Authentication

All endpoints require an API key in the Authorization header:

Authorization: Bearer <api_key>

Base URL

https://api.webrun.ai

Create an Environment

POST /environments
Content-Type: application/json

Field	Type	Required	Description
`name`	string	Yes	Environment name
`description`	string	No	Optional description

curl -X POST https://api.webrun.ai/environments \
  -H "Authorization: Bearer wr_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-environment", "description": "optional description"}'

Response:

{
  "success": true,
  "message": "Environment created",
  "environment": {
    "_id": "<ENV_ID>",
    "userId": "67f1a2b3c4d5e6f7a8b9c0d1",
    "name": "my-environment",
    "description": "optional description",
    "status": "empty",
    "createdAt": "2026-02-09T12:00:00.000Z",
    "updatedAt": "2026-02-09T12:00:00.000Z"
  }
}

Errors

Status	Message	Cause
400	Environment name is required	Missing or empty `name` field
400	Maximum of 20 environments allowed	User already has 20 environments

List Environments

Returns all environments for the authenticated user.

GET /environments

curl https://api.webrun.ai/environments \
  -H "Authorization: Bearer wr_xxx"

Response:

{
  "success": true,
  "environments": [
    {
      "_id": "<ENV_ID>",
      "userId": "67f1a2b3c4d5e6f7a8b9c0d1",
      "name": "my-environment",
      "description": "optional description",
      "status": "ready",
      "createdAt": "2026-02-09T12:00:00.000Z",
      "updatedAt": "2026-02-09T12:30:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
`_id`	string	Unique environment identifier
`userId`	string	Owner’s user ID
`name`	string	Environment name
`description`	string	Environment description
`status`	string	`empty`, `uploading`, or `ready`
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp

Delete an Environment

Permanently deletes an environment, its browser profile data, and all attached files.

DELETE /environments/<ENV_ID>

curl -X DELETE https://api.webrun.ai/environments/<ENV_ID> \
  -H "Authorization: Bearer wr_xxx"

Response:

{
  "success": true,
  "message": "Environment deleted"
}

Errors

Status	Message	Cause
404	Environment not found	Invalid ID or environment belongs to another user

Upload Browser Profile Data

Uploads a .tar.gz Chrome profile archive to an environment. Replaces any existing profile data and sets the status to ready.

POST /environments/<ENV_ID>/upload
Content-Type: multipart/form-data

Parameter	Location	Description
`ENV_ID`	URL path	The environment ID
`file`	Form field	`.tar.gz` profile archive (max 500 MB)

curl -X POST https://api.webrun.ai/environments/<ENV_ID>/upload \
  -H "Authorization: Bearer wr_xxx" \
  -F "file=@/path/to/profile.tar.gz"

Response:

{
  "success": true,
  "message": "Profile uploaded successfully",
  "environment": {
    "_id": "<ENV_ID>",
    "name": "my-environment",
    "status": "ready",
    "blobSize": 4521984,
    "blobUploadedAt": "2026-02-09T12:30:00.000Z"
  }
}

Errors

Status	Message	Cause
400	No file provided	Missing `file` field in form data
400	Only .tar.gz files are allowed	File is not a valid `.tar.gz` archive
404	Environment not found	Invalid ID or environment belongs to another user

To upload your local Chrome profile instead of a manual archive, use the sync tool; it packages and uploads your browser data in one command.

List Files in an Environment

Returns all files attached to an environment.

GET /environments/<ENV_ID>/files

curl https://api.webrun.ai/environments/<ENV_ID>/files \
  -H "Authorization: Bearer wr_xxx"

Response:

{
  "success": true,
  "files": [
    {
      "fileId": "abc123...",
      "originalName": "sample.zip",
      "size": 204800,
      "createdAt": "2026-02-09T12:00:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
`fileId`	string	Unique file identifier
`originalName`	string	Original filename as uploaded
`size`	number	File size in bytes
`createdAt`	string	ISO 8601 upload timestamp

Delete a File from an Environment

Permanently removes a specific file from an environment.

DELETE /environments/<ENV_ID>/files/<FILE_ID>

curl -X DELETE https://api.webrun.ai/environments/<ENV_ID>/files/<FILE_ID> \
  -H "Authorization: Bearer wr_xxx"

Response:

{
  "success": true,
  "message": "File deleted"
}

Errors

Status	Message	Cause
404	File not found	Invalid file ID or file does not belong to this environment

Common Errors

All error responses follow this format:

{
  "success": false,
  "message": "Description of the error"
}

Status	Message	Cause
401	API key required	Missing `Authorization` header
401	Invalid or revoked API key	API key is incorrect or has been revoked
403	Account is deactivated	User account is disabled
500	Authentication error	Server-side authentication failure

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Authentication

Base URL

Create an Environment

Errors

List Environments

Response Fields

Delete an Environment

Errors

Upload Browser Profile Data

Errors

List Files in an Environment

Response Fields

Delete a File from an Environment

Errors

Common Errors

​Authentication

​Base URL

​Create an Environment

​Errors

​List Environments

​Response Fields

​Delete an Environment

​Errors

​Upload Browser Profile Data

​Errors

​List Files in an Environment

​Response Fields

​Delete a File from an Environment

​Errors

​Common Errors

Environments Overview

Triggers

File Uploads

Browser Profiles

Authentication

Base URL

Create an Environment

Errors

List Environments

Response Fields

Delete an Environment

Errors

Upload Browser Profile Data

Errors

List Files in an Environment

Response Fields

Delete a File from an Environment

Errors

Common Errors