Skip to main content
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://connect.webrun.ai

​
Create an Environment

POST /environments
Content-Type: application/json
FieldTypeRequiredDescription
namestringYesEnvironment name
descriptionstringNoOptional description
curl -X POST https://connect.webrun.ai/environments \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \
  -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

StatusMessageCause
400Environment name is requiredMissing or empty name field
400Maximum of 20 environments allowedUser already has 20 environments

​
List Environments

Returns all environments for the authenticated user. 
GET /environments

curl https://connect.webrun.ai/environments \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6"
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

FieldTypeDescription
_idstringUnique environment identifier
userIdstringOwner’s user ID
namestringEnvironment name
descriptionstringEnvironment description
statusstringempty, uploading, or ready
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 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://connect.webrun.ai/environments/<ENV_ID> \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6"
Response: 
{
  "success": true,
  "message": "Environment deleted"
}

​
Errors

StatusMessageCause
404Environment not foundInvalid 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
ParameterLocationDescription
ENV_IDURL pathThe environment ID
fileForm field.tar.gz profile archive (max 500 MB)
curl -X POST https://connect.webrun.ai/environments/<ENV_ID>/upload \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6" \
  -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

StatusMessageCause
400No file providedMissing file field in form data
400Only .tar.gz files are allowedFile is not a valid .tar.gz archive
404Environment not foundInvalid 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://connect.webrun.ai/environments/<ENV_ID>/files \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6"
Response: 
{
  "success": true,
  "files": [
    {
      "fileId": "abc123...",
      "originalName": "sample.zip",
      "size": 204800,
      "createdAt": "2026-02-09T12:00:00.000Z"
    }
  ]
}

​
Response Fields

FieldTypeDescription
fileIdstringUnique file identifier
originalNamestringOriginal filename as uploaded
sizenumberFile size in bytes
createdAtstringISO 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://connect.webrun.ai/environments/<ENV_ID>/files/<FILE_ID> \
  -H "Authorization: Bearer enig_iMM4HaeRczq0sGnyXB8JxhvnYli2pRu6"
Response: 
{
  "success": true,
  "message": "File deleted"
}

​
Errors

StatusMessageCause
404File not foundInvalid 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"
}
StatusMessageCause
401API key requiredMissing Authorization header
401Invalid or revoked API keyAPI key is incorrect or has been revoked
403Account is deactivatedUser account is disabled
500Authentication errorServer-side authentication failure