> ## 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.

# Parameters

> Complete reference for all WebRun API parameters

## Session Parameters

Parameters used when creating a new session via `POST /start/start-session`.

### environmentId

* **Type:** `string`
* **Required:** No
* **Default:** `null`
* **Description:** ID of an [environment](/environments/overview) to attach to the session. When set, the browser loads the environment's saved cookies, local storage, extensions, and other browser data before starting the task. Files stored in the environment are also available to the session. This maintains consistent browser state (e.g., login sessions) and persistent file access across multiple sessions.

**Example:**

```json theme={null}
{
  "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",
  "mode": "default",
  "task": {
    "prompt": "Go to amazon.com and check my orders"
  }
}
```

<Tip>
  Use profiles to skip login steps. Log in once with a profile attached, then reuse that profile for future sessions — the saved cookies keep you authenticated.
</Tip>

***

### policyId

* **Type:** `string`
* **Required:** No
* **Default:** `null`
* **Description:** ID of an [automation policy](/concepts/policies) to enforce during the session. When set, every agent action is evaluated against the policy's rules before execution. Actions can be allowed, blocked, or paused for human approval depending on the matching rule. Policies cover domain restrictions, keyword filters, action types, URL patterns, and sensitive data detection.

**Example:**

```json theme={null}
{
  "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",
  "policyId": "pol_xyz789",
  "mode": "default",
  "task": {
    "prompt": "Extract the latest invoice from the vendor portal",
    "startingUrl": "https://vendor.example.com"
  }
}
```

<Note>
  `policyId` is a top-level session parameter, alongside `environmentId` and `proxy`. A session can have a policy, an environment, both, or neither. See [Automation Policies](/concepts/policies) for details.
</Note>

***

### proxy

* **Type:** `object | null`
* **Required:** No
* **Default:** `null`
* **Description:** Proxy configuration for the session. Routes all browser traffic through the specified proxy server. The proxy is applied at the device level, ensuring no IP leakage. Adds 2-3 seconds of cold-start latency per session.

**Two proxy sources are available:**

| Source   | Description                                      | Cost                 |
| -------- | ------------------------------------------------ | -------------------- |
| `WebRun` | WebRun assigns a residential proxy from its pool | \$4 per GB           |
| `custom` | Bring your own HTTP or SOCKS proxy               | No additional charge |

**WebRun Proxy Fields:**

| Field     | Type     | Required | Description                                                                                                                                                                                                                                                                                                         |
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`  | `string` | Yes      | `"WebRun"`                                                                                                                                                                                                                                                                                                          |
| `country` | `string` | Yes      | ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`, `"DE"`) or `"random"`                                                                                                                                                                                                                                         |
| `level`   | `string` | No       | Proxy level: `"system"` or `"chrome"`. When omitted, routed to the best available connection that matches the country. `system` applies the proxy at the system level (no IP leakage, slower cold start). `chrome` applies the proxy to Chrome directly (faster cold start, may leak IP in edge cases like WebRTC). |

**Custom Proxy Fields:**

| Field      | Type     | Required | Description                                                                                                                        |
| ---------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `source`   | `string` | Yes      | `"custom"`                                                                                                                         |
| `type`     | `string` | Yes      | `"http"` or `"socks"`                                                                                                              |
| `host`     | `string` | Yes      | Proxy server hostname or IP                                                                                                        |
| `port`     | `string` | Yes      | Proxy server port                                                                                                                  |
| `username` | `string` | No       | Authentication username                                                                                                            |
| `password` | `string` | No       | Authentication password                                                                                                            |
| `level`    | `string` | No       | Proxy level: `"system"` or `"chrome"`. When omitted, routed to the best available connection. See WebRun proxy fields for details. |

**Examples:**

```json theme={null}
// WebRun-managed proxy (default level)
{
  "proxy": {
    "source": "WebRun",
    "country": "US"
  }
}

// WebRun-managed proxy with system level
{
  "proxy": {
    "source": "WebRun",
    "country": "US",
    "level": "system"
  }
}

// Custom HTTP proxy
{
  "proxy": {
    "source": "custom",
    "type": "http",
    "host": "proxy.example.com",
    "port": "8080",
    "username": "user",
    "password": "pass"
  }
}

// Custom SOCKS proxy
{
  "proxy": {
    "source": "custom",
    "type": "socks",
    "host": "proxy.example.com",
    "port": "1080",
    "username": "user",
    "password": "pass"
  }
}

// No proxy (default)
{
  "proxy": null
}
```

<Note>
  The `proxy` field is a top-level session parameter, alongside `environmentId`. It is not nested inside `task`. The proxy applies to the entire session — all tasks within the session use the same proxy.
</Note>

See [Proxies guide](/usage-guides/proxies) for use cases and best practices.

***

### mode

* **Type:** `string`
* **Required:** No
* **Default:** `"default"`
* **Description:** Session mode. Currently only `"default"` is supported.

**Example:**

```json theme={null}
{
  "mode": "default"
}
```

***

### reachOutMode

* **Type:** `string` — one of `"off"`, `"guardrail_only"`, `"full"`
* **Required:** No
* **Default:** `"guardrail_only"`
* **Description:** Controls whether the chat-connected user (Telegram, WhatsApp, Slack, Discord, Teams) on the session's [environment](/environments/overview) receives proactive messages from this session. The chat user is only contacted when no client is actively watching the session (no polling or WebSocket subscriber). This is a top-level session parameter and applies for the lifetime of the session.

**Allowed values:**

| Value              | Behavior                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `"off"`            | No proactive messages — guardrails and results stay on the API/WebSocket channel only.                                         |
| `"guardrail_only"` | Bot pings the chat user only when the session hits a guardrail (CAPTCHA, 2FA, verification, login, etc.). This is the default. |
| `"full"`           | Bot pings on guardrails **and** on `task_completed` with the task result delivered to chat.                                    |

**Validation:** Invalid values return `400 Bad Request` with the error message `reachOutMode must be one of: off, guardrail_only, full`.

**Example:**

```json theme={null}
{
  "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",
  "reachOutMode": "full",
  "mode": "default",
  "task": {
    "prompt": "Export the monthly financial report"
  }
}
```

<Note>
  The mode is locked at session creation. To change the behavior, create a new session. See [Routing Guardrails to a Chat User](/usage-guides/handling-guardrails#routing-guardrails-to-a-chat-user) for the full flow.
</Note>

***

### task

* **Type:** `object`
* **Required:** No
* **Description:** Configuration for the task to run when the session starts. Contains all task-specific parameters.

**Example with structured\_json:**

```json theme={null}
{
  "mode": "default",
  "task": {
    "prompt": "Find the price of iPhone 15 Pro on Apple.com",
    "startingUrl": "https://apple.com",
    "maxDuration": 300000,
    "outputType": "structured_json",
    "outputSchema": {
      "type": "object",
      "properties": {
        "productName": { "type": "string" },
        "price": { "type": "number" },
        "currency": { "type": "string" }
      }
    }
  }
}
```

**Example with structured\_csv:**

```json theme={null}
{
  "mode": "default",
  "task": {
    "prompt": "Get the top 10 cryptocurrency prices",
    "maxDuration": 300000,
    "outputType": "structured_csv",
    "outputSchema": ["name", "price", "market_cap"]
  }
}
```

<Note>
  All task-specific parameters like `prompt`, `startingUrl`, `outputType`, and `outputSchema` are now nested inside the `task` object.
</Note>

***

## Task Parameters

Parameters used inside the `task` object when creating a session, or in the message body when sending a new task via `POST /start/send-message`.

### prompt

* **Type:** `string`
* **Required:** No
* **Default:** `""`
* **Description:** Task description for the AI agent to execute.

**Example:**

```json theme={null}
{
  "task": {
    "prompt": "Go to amazon.com and search for wireless keyboards"
  }
}
```

***

### startingUrl

* **Type:** `string`
* **Required:** No
* **Default:** `null`
* **Description:** URL where the browser should navigate before starting the task. Speeds up task execution by starting at the relevant page.

**Example:**

```json theme={null}
{
  "task": {
    "prompt": "Search for laptops",
    "startingUrl": "https://amazon.com"
  }
}
```

<Tip>
  Setting a `startingUrl` eliminates the need to navigate from a blank page, reducing task execution time and cost.
</Tip>

***

### maxDuration

* **Type:** `number` (milliseconds)
* **Required:** No
* **Default:** `300000` (5 minutes)
* **Maximum:** `300000` (5 minutes)
* **Description:** Maximum time a task can run before automatic termination.

**Example:**

```json theme={null}
{
  "maxDuration": 180000  // 3 minutes
}
```

<Warning>
  Tasks automatically terminate after `maxDuration`. Set this value based on your expected task completion time.
</Warning>

***

### maxInputTokens

* **Type:** `number`
* **Required:** No
* **Default:** `100000`
* **Description:** Maximum number of input tokens the AI can process. Limits context size to control costs.

**Example:**

```json theme={null}
{
  "maxInputTokens": 50000
}
```

***

### maxOutputTokens

* **Type:** `number`
* **Required:** No
* **Default:** `100000`
* **Description:** Maximum number of output tokens the AI can generate. Limits response size to control costs.

**Example:**

```json theme={null}
{
  "maxOutputTokens": 50000
}
```

***

### terminateOnCompletion

* **Type:** `boolean`
* **Required:** No
* **Default:** `false`
* **Description:** Whether to automatically terminate the session after the current task completes. Set to `true` to prevent idle session charges.

**Example:**

```json theme={null}
{
  "terminateOnCompletion": true
}
```

<Tip>
  **💰 Cost Optimization:** Set `terminateOnCompletion: true` on your last task to automatically close the session and prevent idle charges.
</Tip>

***

### outputType

* **Type:** `string`
* **Required:** No
* **Default:** `"text"`
* **Values:** `"text"`, `"structured_json"`, `"structured_csv"`
* **Description:** Specifies the output format.

| Value             | Description                       | Schema Format         |
| ----------------- | --------------------------------- | --------------------- |
| `text`            | Markdown formatted text (default) | Not required          |
| `structured_json` | Validated JSON output             | JSON Schema object    |
| `structured_csv`  | CSV formatted data                | Array of column names |

**Examples:**

```json theme={null}
// Text output (default)
{
  "outputType": "text"
}

// JSON output with schema
{
  "outputType": "structured_json",
  "outputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" }
    }
  }
}

// CSV output with column names
{
  "outputType": "structured_csv",
  "outputSchema": ["name", "price", "quantity"]
}
```

<Note>
  When using `outputType: "structured_json"` or `"structured_csv"`, you must also provide an `outputSchema` to define the expected response structure.
</Note>

***

### outputSchema

* **Type:** `object` (JSON Schema) or `array` (column names)
* **Required:** No (required when `outputType` is `"structured_json"` or `"structured_csv"`)
* **Description:** Defines the expected response structure. The format depends on the `outputType`:
  * For `structured_json`: A JSON Schema object
  * For `structured_csv`: An array of column name strings

**Example for structured\_json:**

```json theme={null}
{
  "outputType": "structured_json",
  "outputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "price": { "type": "number" },
      "inStock": { "type": "boolean" },
      "features": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["title", "price"],
    "additionalProperties": false
  }
}
```

**Supported JSON Schema Types:**

* `string` - Text values
* `number` - Numeric values (integers and decimals)
* `boolean` - True/false values
* `object` - Nested objects with defined properties
* `array` - Arrays with defined item structure

**Example for structured\_csv:**

```json theme={null}
{
  "outputType": "structured_csv",
  "outputSchema": ["name", "price", "quantity", "category"]
}
```

The CSV output will include a header row with the specified column names, followed by data rows.

<Tip>
  For JSON schemas, use `"additionalProperties": false` to ensure the output contains only the fields you specify.
</Tip>

***

### secrets

* **Type:** `array`
* **Required:** No
* **Default:** `[]`
* **Description:** Array of secret entries to provide credentials for websites the agent visits. Secrets are matched by domain pattern so the agent uses the right credentials for each site.

**Secret Entry Structure:**

| Field    | Type     | Required | Description                                                                    |
| -------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `match`  | `string` | Yes      | Domain pattern to match (e.g. `*.salesforce.com`) or `all` to match every site |
| `fields` | `object` | Yes      | Key-value pairs of credential fields (e.g. `email`, `password`, `apiKey`)      |

**Example:**

```json theme={null}
{
  "secrets": [
    {
      "match": "*.salesforce.com",
      "fields": {
        "email": "user@company.com",
        "password": "secretpass"
      }
    },
    {
      "match": "all",
      "fields": {
        "email": "user@company.com",
        "password": "defaultpass"
      }
    }
  ]
}
```

<Note>
  Secrets are never stored in a database or persisted anywhere. They are only attached to the active session and immediately discarded once the session is destroyed. Secrets are never included in task output or webhook payloads.
</Note>

See [Secrets guide](/usage-guides/secrets) for matching rules, custom fields, and best practices.

***

### files

* **Type:** `string[]` (array of file ID strings)
* **Required:** No
* **Default:** `[]`
* **Description:** Array of file IDs (returned from `POST /files/upload`) to attach to a task. The agent can use these files during browser automation — for example, uploading a document to a website form. This is a task-level parameter — place it alongside `prompt`.

**Example with /start/run-task:**

```json theme={null}
{
  "prompt": "Upload this document to the submission form",
  "startingUrl": "https://example.com/upload",
  "files": ["abc123...", "def456..."]
}
```

**Example with /start/start-session:**

```json theme={null}
{
  "mode": "default",
  "task": {
    "prompt": "Upload the attached file to the portal",
    "startingUrl": "https://example.com/portal",
    "files": ["abc123..."]
  }
}
```

See [File Uploads guide](/environments/file-uploads) for the full upload workflow.

***

### webhook

* **Type:** `object`
* **Required:** No
* **Description:** Webhook configuration for receiving task completion notifications.

**Webhook Object Structure:**

| Field           | Type     | Required | Description                         |
| --------------- | -------- | -------- | ----------------------------------- |
| `name`          | `string` | Yes      | Identifier for this webhook         |
| `url`           | `string` | Yes      | Endpoint URL to receive the webhook |
| `auth`          | `string` | No       | Authorization header value          |
| `submittedData` | `string` | Yes      | Data to include in the payload      |

**submittedData Options:**

* `"ai_response"` - The response from the AI (text, structured\_json, or structured\_csv) — only the results/output from the LLM
* `"full_response"` - Full body response that includes the usage info
* `"just_ping"` - Just a ping notification, no data payload

**Example:**

```json theme={null}
{
  "webhook": {
    "name": "Product Webhook",
    "url": "https://api.yoursite.com/webhooks/products",
    "auth": "Bearer your-secret-token",
    "submittedData": "ai_response"
  }
}
```

**Complete Example with Structured Output and Webhook:**

```json theme={null}
{
  "mode": "default",
  "task": {
    "prompt": "Extract product information from the page",
    "startingUrl": "https://example.com/product",
    "maxDuration": 300000,
    "outputType": "structured_json",
    "outputSchema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "price": { "type": "number" },
        "inStock": { "type": "boolean" }
      },
      "required": ["title", "price"],
      "additionalProperties": false
    },
    "webhook": {
      "name": "Product Webhook",
      "url": "https://api.mysite.com/products",
      "auth": "Bearer token123",
      "submittedData": "ai_response"
    }
  }
}
```

***

## Task Parameters

Parameters used when starting a new task via `POST /start/send-message` with `actionType: "newTask"`.

All [Task Parameters](#task-parameters) are available, plus:

### actionType

* **Type:** `string`
* **Required:** Yes
* **Values:** `"newTask"`, `"state"`, `"interaction"`, `"guardrail"`
* **Description:** Type of action to perform on the session.

**Example:**

```json theme={null}
{
  "actionType": "newTask"
}
```

***

### newState

* **Type:** `string`
* **Required:** Yes (for `actionType: "newTask"` and `actionType: "state"`)
* **Values:**
  * For tasks: `"start"`
  * For state control: `"pause"`, `"resume"`, `"stop"`, `"terminate"`
* **Description:** State change to apply.

**Examples:**

```json theme={null}
// Starting a new task
{
  "actionType": "newTask",
  "newState": "start"
}

// Pausing execution
{
  "actionType": "state",
  "newState": "pause"
}

// Resuming execution
{
  "actionType": "state",
  "newState": "resume"
}
```

***

## Message Parameters

Parameters used in the `message` field of `POST /start/send-message`.

### For State Control (actionType: "state")

**Required Parameters:**

* `actionType`: `"state"`
* `newState`: `"pause" | "resume" | "stop" | "terminate"`

**Example:**

```json theme={null}
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "state",
    "newState": "pause"
  }
}
```

***

### For Manual Interaction (actionType: "interaction")

**Required Parameters:**

* `actionType`: `"interaction"`
* `action`: Object containing interaction details

**Action Object Structure:**

#### takeOverControl / releaseControl

```json theme={null}
{
  "type": "takeOverControl"
}
// or
{
  "type": "releaseControl"
}
```

#### CLICK / DOUBLE\_CLICK

```json theme={null}
{
  "type": "CLICK",  // or "DOUBLE_CLICK"
  "x": 500,
  "y": 300
}
```

**Parameters:**

* `x` (number): Horizontal coordinate (0-1024)
* `y` (number): Vertical coordinate (155-600, accounting for browser chrome)

<Note>
  **Coordinate System:** The browser viewport is 1024×600 pixels. The top 155 pixels are browser chrome (not clickable). Clickable area is 1024×445 pixels starting at Y=155.
</Note>

#### TYPE

```json theme={null}
{
  "type": "TYPE",
  "text": "Hello world",
  "humanLike": true
}
```

**Parameters:**

* `text` (string, required): Text to type
* `humanLike` (boolean, optional): Simulate human typing speed

#### KEY\_PRESS

```json theme={null}
{
  "type": "KEY_PRESS",
  "key": "Enter"
}
```

**Parameters:**

* `key` (string, required): Key to press

**Common Keys:**

* `Enter`
* `Escape`
* `Tab`
* `Backspace`
* `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`

***

### For Guardrail Response (actionType: "guardrail")

**Required Parameters:**

* `actionType`: `"guardrail"`
* `prompt`: Human-provided information
* `newState`: `"resume"`

**Example:**

```json theme={null}
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "guardrail",
    "prompt": "Username: user@example.com, Password: pass123",
    "newState": "resume"
  }
}
```

***

## Response Fields

Fields returned in API responses.

### Session Response Fields

Returned from `POST /start/start-session`:

| Field                  | Type    | Description                                   |
| ---------------------- | ------- | --------------------------------------------- |
| `success`              | boolean | Whether the request succeeded                 |
| `sessionId`            | string  | Unique session identifier                     |
| `socketURL`            | string  | WebSocket connection URL                      |
| `streaming`            | object  | Video streaming configuration                 |
| `streaming.webRTCURL`  | string  | WebRTC WHEP endpoint URL                      |
| `streaming.webViewURL` | string  | HTTP video stream URL                         |
| `streaming.dimensions` | object  | Video dimensions `{width: 1024, height: 600}` |
| `initialPrompt`        | string  | The initial task that was provided            |
| `expiresIn`            | number  | Session expiration time in milliseconds       |
| `balance`              | number  | Current account balance in USD                |
| `message`              | string  | Additional information                        |

***

### Task Response Fields

Returned from `POST /start/send-message` with `actionType: "newTask"` and `POST /start/run-task`:

**When task completes within 50 seconds:**

| Field                           | Type    | Description                     |
| ------------------------------- | ------- | ------------------------------- |
| `success`                       | boolean | Whether the request succeeded   |
| `sessionId`                     | string  | Session identifier              |
| `taskId`                        | string  | Task identifier                 |
| `status`                        | string  | Task status: `"complete"`       |
| `result`                        | object  | Task result details             |
| `result.type`                   | string  | Result type: `"task_completed"` |
| `result.data`                   | object  | Result data                     |
| `result.data.message`           | string  | Task completion message         |
| `result.data.prompt_tokens`     | number  | Input tokens used               |
| `result.data.completion_tokens` | number  | Output tokens generated         |
| `result.data.total_tokens`      | number  | Total tokens used               |
| `result.data.completion_time`   | number  | Task execution time in seconds  |

**When task is still running after 50 seconds:**

| Field       | Type    | Description                       |
| ----------- | ------- | --------------------------------- |
| `success`   | boolean | Whether the request succeeded     |
| `sessionId` | string  | Session identifier                |
| `taskId`    | string  | Task identifier for polling       |
| `status`    | string  | Task status: `"pending"`          |
| `pending`   | boolean | `true` when task is still running |
| `pollUrl`   | string  | URL to poll for task result       |
| `message`   | string  | Instruction to poll for result    |

***

### Poll Response Fields

Returned from `GET /task/:sessionId/:taskId`:

**While running:**

| Field                | Type    | Description                       |
| -------------------- | ------- | --------------------------------- |
| `success`            | boolean | Whether the request succeeded     |
| `status`             | string  | Task status: `"active"`           |
| `pending`            | boolean | `true` when task is still running |
| `usage`              | object  | Current usage statistics          |
| `usage.inputTokens`  | number  | Input tokens used so far          |
| `usage.outputTokens` | number  | Output tokens generated so far    |
| `usage.computeTime`  | number  | Compute time in seconds           |
| `usage.cost`         | number  | Cost in USD so far                |

**When completed:**

| Field                    | Type    | Description                      |
| ------------------------ | ------- | -------------------------------- |
| `success`                | boolean | Whether the request succeeded    |
| `type`                   | string  | Result type: `"task_completed"`  |
| `data`                   | object  | Task result data                 |
| `data.message`           | string  | Task completion message          |
| `data.prompt_tokens`     | number  | Total input tokens used          |
| `data.completion_tokens` | number  | Total output tokens generated    |
| `data.total_tokens`      | number  | Total tokens used                |
| `data.completion_time`   | number  | Task execution time in seconds   |
| `usage`                  | object  | Final usage statistics           |
| `usage.inputTokens`      | number  | Total input tokens               |
| `usage.outputTokens`     | number  | Total output tokens              |
| `usage.computeTime`      | number  | Total compute time in seconds    |
| `usage.cost`             | number  | Total cost in USD                |
| `completedAt`            | string  | ISO 8601 timestamp of completion |

**When guardrail triggered:**

| Field        | Type    | Description                                   |
| ------------ | ------- | --------------------------------------------- |
| `success`    | boolean | Whether the request succeeded                 |
| `type`       | string  | Result type: `"guardrail_trigger"`            |
| `data`       | object  | Guardrail details                             |
| `data.type`  | string  | Guardrail type (e.g., `"human_input_needed"`) |
| `data.value` | string  | Guardrail message explaining what's needed    |

**When failed:**

| Field     | Type    | Description                               |
| --------- | ------- | ----------------------------------------- |
| `success` | boolean | `false`                                   |
| `status`  | string  | `"failed"`                                |
| `error`   | string  | Error message                             |
| `code`    | string  | Error code (e.g., `"NAVIGATION_TIMEOUT"`) |
| `usage`   | object  | Usage statistics up to failure            |

***

### Usage Object Structure

The `usage` object provides token and cost information:

```typescript theme={null}
{
  inputTokens: number;      // Number of input tokens used
  outputTokens: number;     // Number of output tokens generated
  computeTime: number;      // Compute time in seconds
  cost: number;             // Cost in USD
}
```

**Example:**

```json theme={null}
{
  "usage": {
    "inputTokens": 12450,
    "outputTokens": 3200,
    "computeTime": 5,
    "cost": 0.0124
  }
}
```

***

## OpenAI-Compatible Parameters

Parameters for `POST /v1/chat/completions`.

### model

* **Type:** `string`
* **Required:** Yes
* **Value:** `"enigma-browser-1"`
* **Description:** Model to use. Currently only `enigma-browser-1` is available.

***

### messages

* **Type:** `array` of message objects
* **Required:** Yes
* **Description:** Array of conversation messages

**Message Object Structure:**

```typescript theme={null}
{
  role: "system" | "user" | "assistant";
  content: string;
}
```

**Example:**

```json theme={null}
{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful browser automation assistant."
    },
    {
      "role": "user",
      "content": "Go to example.com and extract all headings"
    }
  ]
}
```

***

### stream

* **Type:** `boolean`
* **Required:** No
* **Default:** `false`
* **Description:** Enable streaming responses via Server-Sent Events (SSE).

***

### max\_tokens

* **Type:** `number`
* **Required:** No
* **Default:** `2000`
* **Description:** Maximum number of tokens in the response.

***

### temperature

* **Type:** `number`
* **Required:** No
* **Description:** Not used (included for OpenAI compatibility only). Task execution is deterministic.

***

## Type Definitions

### ActionType

```typescript theme={null}
type ActionType = "newTask" | "state" | "interaction" | "guardrail";
```

***

### StateType

```typescript theme={null}
type StateType = "start" | "pause" | "resume" | "stop" | "terminate";
```

***

### InteractionType

```typescript theme={null}
type InteractionType =
  | "takeOverControl"
  | "releaseControl"
  | "CLICK"
  | "DOUBLE_CLICK"
  | "TYPE"
  | "KEY_PRESS";
```

***

### OutputType

```typescript theme={null}
type OutputType = "text" | "structured_json" | "structured_csv";
```

***

### OutputSchema

For `structured_json`, use a JSON Schema object:

```typescript theme={null}
interface JsonOutputSchema {
  type: "object" | "array" | "string" | "number" | "boolean";
  properties?: Record<string, JsonOutputSchema>;
  items?: JsonOutputSchema;
  required?: string[];
  additionalProperties?: boolean;
}
```

For `structured_csv`, use an array of column names:

```typescript theme={null}
type CsvOutputSchema = string[];
```

Combined type:

```typescript theme={null}
type OutputSchema = JsonOutputSchema | CsvOutputSchema;
```

***

### WebhookConfig

```typescript theme={null}
interface WebhookConfig {
  name: string;
  url: string;
  auth?: string;
  submittedData: "ai_response" | "full_response" | "just_ping";
}
```

***

### SecretEntry

```typescript theme={null}
interface SecretEntry {
  match: string;       // Domain pattern (e.g. "*.salesforce.com") or "all"
  fields: Record<string, string>; // Key-value credential fields
}
```

***

\###TaskConfig

```typescript theme={null}
interface TaskConfig {
  prompt?: string;
  startingUrl?: string | null;
  maxDuration?: number;
  maxInputTokens?: number;
  maxOutputTokens?: number;
  terminateOnCompletion?: boolean;
  outputType?: OutputType;
  outputSchema?: OutputSchema;
  webhook?: WebhookConfig;
  secrets?: SecretEntry[];
  files?: string[];
}
```

***

### ProxyConfig

```typescript theme={null}
// WebRun-managed proxy
interface WebRunProxy {
  source: "WebRun";
  country: string;  // ISO 3166-1 alpha-2 code or "random"
  level?: "system" | "chrome";  // Default: best available connection
}

// Custom proxy (HTTP or SOCKS)
interface CustomProxy {
  source: "custom";
  type: "http" | "socks";
  host: string;
  port: string;
  username?: string;
  password?: string;
  level?: "system" | "chrome";  // Default: best available connection
}

type ProxyConfig = WebRunProxy | CustomProxy;
```

***

### SessionConfig

```typescript theme={null}
interface SessionConfig {
  environmentId?: string;
  policyId?: string;
  proxy?: ProxyConfig | null;
  reachOutMode?: "off" | "guardrail_only" | "full";  // Default: "guardrail_only"
  mode?: string;
  task?: TaskConfig;
}
```

***

### TaskMessage

```typescript theme={null}
interface TaskMessage {
  actionType: "newTask";
  newState: "start";
  prompt: string;
  startingUrl?: string | null;
  maxDuration?: number;
  maxInputTokens?: number;
  maxOutputTokens?: number;
  terminateOnCompletion?: boolean;
  outputType?: OutputType;
  outputSchema?: OutputSchema;
  webhook?: WebhookConfig;
  secrets?: SecretEntry[];
  files?: string[];
}
```

***

### StateMessage

```typescript theme={null}
interface StateMessage {
  actionType: "state";
  newState: "pause" | "resume" | "stop" | "terminate";
}
```

***

### InteractionMessage

```typescript theme={null}
interface InteractionMessage {
  actionType: "interaction";
  action:
    | { type: "takeOverControl" }
    | { type: "releaseControl" }
    | { type: "CLICK" | "DOUBLE_CLICK"; x: number; y: number }
    | { type: "TYPE"; text: string; humanLike?: boolean }
    | { type: "KEY_PRESS"; key: string };
}
```

***

### GuardrailMessage

```typescript theme={null}
interface GuardrailMessage {
  actionType: "guardrail";
  prompt: string;
  newState: "resume";
}
```

***

## Parameter Validation

### Constraints

| Parameter            | Min  | Max       | Notes                            |
| -------------------- | ---- | --------- | -------------------------------- |
| `maxDuration`        | 1000 | 300000    | Milliseconds (max task duration) |
| `maxInputTokens`     | 0    | 100000    | Default: 100000                  |
| `maxOutputTokens`    | 0    | 100000    | Default: 100000                  |
| `max_tokens`         | 0    | unlimited | OpenAI-compatible endpoint       |
| Click `x` coordinate | 0    | 1024      | Browser width                    |
| Click `y` coordinate | 155  | 600       | Accounting for browser chrome    |

***

<Accordion title="Related">
  <CardGroup cols={2}>
    <Card title="Endpoints" icon="plug" href="/api-reference/endpoints">
      Complete endpoint reference
    </Card>

    <Card title="Response Formats" icon="code" href="/api-reference/response-formats">
      Response format reference
    </Card>
  </CardGroup>
</Accordion>