> ## Documentation Index > Fetch the complete documentation index at: https://docs.webrun.ai/llms.txt > Use this file to discover all available pages before exploring further. # Environments API > Create, list, and delete environments; upload browser profiles and manage attached files 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: ```bash theme={null} Authorization: Bearer ``` ## 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 | ```bash theme={null} 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:** ```json theme={null} { "success": true, "message": "Environment created", "environment": { "_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 ``` ```bash theme={null} curl https://api.webrun.ai/environments \ -H "Authorization: Bearer wr_xxx" ``` **Response:** ```json theme={null} { "success": true, "environments": [ { "_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/ ``` ```bash theme={null} curl -X DELETE https://api.webrun.ai/environments/ \ -H "Authorization: Bearer wr_xxx" ``` **Response:** ```json theme={null} { "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//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) | ```bash theme={null} curl -X POST https://api.webrun.ai/environments//upload \ -H "Authorization: Bearer wr_xxx" \ -F "file=@/path/to/profile.tar.gz" ``` **Response:** ```json theme={null} { "success": true, "message": "Profile uploaded successfully", "environment": { "_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](/environments/profiles#sync-from-local-chrome); it packages and uploads your browser data in one command. *** ## List Files in an Environment Returns all files attached to an environment. ``` GET /environments//files ``` ```bash theme={null} curl https://api.webrun.ai/environments//files \ -H "Authorization: Bearer wr_xxx" ``` **Response:** ```json theme={null} { "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//files/ ``` ```bash theme={null} curl -X DELETE https://api.webrun.ai/environments//files/ \ -H "Authorization: Bearer wr_xxx" ``` **Response:** ```json theme={null} { "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: ```json theme={null} { "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 | *** What environments are and when to use them Schedule recurring tasks under an environment Upload files for use in sessions How browser profiles work, sync from local Chrome This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.