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

# Endpoints

> Complete reference for all WebRun API endpoints

## Base URL

```
https://connect.webrun.ai
```

All endpoints use this base URL unless otherwise specified.

***

## Session Endpoints

### POST /start/start-session

Create a new persistent session that can run multiple tasks.

**Authentication:** Required

**Request Body:**

```json theme={null}
{
  "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",
  "policyId": "pol_xyz789",
  "proxy": { "source": "WebRun", "country": "US" },
  "reachOutMode": "guardrail_only",
  "mode": "default",
  "task": {
    "prompt": "Go to amazon.com and search for laptops",
    "startingUrl": "https://amazon.com",
    "maxDuration": 300000,
    "maxInputTokens": 100000,
    "maxOutputTokens": 100000,
    "terminateOnCompletion": false,
    "outputType": "structured_json",
    "outputSchema": {
      "type": "object",
      "properties": {
        "results": { "type": "array" }
      }
    },
    "secrets": [
      {
        "match": "*.amazon.com",
        "fields": { "email": "user@example.com", "password": "pass123" }
      }
    ]
  }
}
```

<Note>
  The `task` object contains all task-specific parameters. Use `startingUrl` to specify the URL where the task should begin. Use `environmentId` (top-level) to attach an [environment](/environments/overview) with saved cookies, browser state, and persistent files. Use `policyId` (top-level) to enforce [automation policy](/concepts/policies) rules on agent actions. Use `proxy` (top-level) to route the session through a [proxy server](/usage-guides/proxies).
</Note>

**Response (200 OK):**

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "socketURL": "https://connect.webrun.ai",
  "streaming": {
    "webRTCURL": "https://74.235.190.31:8889/a1b2c3d4e5f6/whep",
    "webViewURL": "https://74.235.190.31:8889/a1b2c3d4e5f6",
    "dimensions": { "width": 1024, "height": 600 }
  },
  "initialPrompt": "Go to amazon.com",
  "expiresIn": 300000,
  "balance": 12.50,
  "message": "Connect to instance using sessionId in auth"
}
```

**Error Responses:**

* `401` - Missing or invalid API key
* `402` - Insufficient balance
* `403` - Account deactivated
* `429` - Rate limit exceeded
* `503` - No available instances

See [Parameters Reference](/api-reference/parameters) for detailed parameter descriptions.

***

### POST /start/send-message

Universal endpoint for all session control commands. Handles tasks, state changes, interactions, and guardrails.

**Authentication:** Required

**Request Body:**

```json theme={null}
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "newTask | state | interaction | guardrail",
    // ... action-specific fields
  }
}
```

**Supported Action Types:**

#### actionType: newTask

Start a new task. Returns taskId for polling.

```json theme={null}
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "newTask",
    "newState": "start",
    "prompt": "Search for laptops",
    "startingUrl": "https://amazon.com",
    "files": ["abc123..."],
    "maxDuration": 60000,
    "maxInputTokens": 50000,
    "maxOutputTokens": 50000,
    "terminateOnCompletion": true,
    "outputType": "structured_json",
    "outputSchema": {
      "type": "object",
      "properties": {
        "products": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "price": { "type": "number" }
            }
          }
        }
      }
    }
  }
}
```

**Response (completed within 50 seconds):**

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Found 50 laptop results",
    "files": [],
    "network": [
      {
        "id": "abc12",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://www.amazon.com/s?k=laptops",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 8500,
    "completion_tokens": 2300,
    "total_tokens": 10800,
    "completion_time": 18.3,
    "cost": 0.0087
  }
}
```

**Response (still running):**

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "pending",
  "pollUrl": "https://connect.webrun.ai/task/a1b2c3d4e5f6/x9y8z7w6v5u4"
}
```

#### actionType: state

Control task execution (pause, resume, stop, terminate). Returns immediate success.

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

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Message sent successfully"
}
```

#### actionType: interaction

Manual browser control. Returns immediate success.

```json theme={null}
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "interaction",
    "action": {
      "type": "CLICK | TYPE | KEY_PRESS | takeOverControl | releaseControl",
      // ... action-specific parameters
    }
  }
}
```

**Available Interaction Types:**

* `takeOverControl` - Enable manual mode
* `releaseControl` - Return control to AI
* `CLICK` - Click at coordinates `{x, y}`
* `DOUBLE_CLICK` - Double click at coordinates `{x, y}`
* `TYPE` - Type text `{text, humanLike}`
* `KEY_PRESS` - Press key `{key}`

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Message sent successfully"
}
```

#### actionType: guardrail

Respond to guardrail trigger. Returns immediate success.

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

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Message sent successfully"
}
```

**Error Responses:**

* `400` - Missing required fields (sessionId, message)
* `401` - Session not found or unauthorized

***

### POST /start/run-task

Execute a single task with auto-terminating session. Simplified version of start-session + send-message.

**Authentication:** Required

<Note>
  `terminateOnCompletion` is automatically set to `true` for this endpoint. The session will close after task completion.
</Note>

**Request Body:**

```json theme={null}
{
  "task": {
    "prompt": "Search Google for Anthropic",
    "startingUrl": "https://google.com",
    "files": ["abc123..."],
    "maxDuration": 300000,
    "maxInputTokens": 100000,
    "maxOutputTokens": 100000
  },
  "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",
  "policyId": "pol_xyz789",
  "proxy": { "source": "WebRun", "country": "US" },
  "reachOutMode": "guardrail_only",
  "mode": "default"
}
```

**Response (completed within 50 seconds):**

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Successfully searched for Anthropic",
    "files": [],
    "network": [
      {
        "id": "tevo9",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://www.google.com/search?q=Anthropic",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5,
    "cost": 0.0124
  }
}
```

**Response (still running):**

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "pending",
  "pollUrl": "https://connect.webrun.ai/task/a1b2c3d4e5f6/x9y8z7w6v5u4",
  "message": "Task still running. Poll GET /task/:sessionId/:taskId for result."
}
```

**Error Responses:**

* `400` - Missing task.prompt
* `401` - Missing or invalid API key
* `402` - Insufficient balance
* `503` - No available instances

***

## File Upload Endpoints

### POST /files/upload

Upload one or more files to use in tasks. Returns `fileId` references that can be attached to any task endpoint.

**Authentication:** Required

**Content-Type:** `multipart/form-data`

**Request:**

```bash theme={null}
curl -X POST https://connect.webrun.ai/files/upload \
  -H "Authorization: Bearer enig_xxx" \
  -F "files=@document.pdf"
```

**Response (200 OK):**

```json theme={null}
{
  "success": true,
  "files": [
    {
      "fileId": "abc123...",
      "originalName": "document.pdf",
      "size": 102400
    }
  ]
}
```

Use the returned `fileId` values in the `files` array at the task level — inside `task` for `/start/start-session`, in the request body for `/start/run-task`, or inside `message` for `/start/send-message`.

See [File Uploads guide](/environments/file-uploads) for complete examples.

***

## Task Endpoints

### GET /task/:sessionId/:taskId

Poll for task result.

**Path Parameters:**

* `sessionId` - Session identifier
* `taskId` - Task identifier

**Response (still running):**

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "running",
  "usage": {
    "prompt_tokens": 8000,
    "completion_tokens": 2100,
    "total_tokens": 10100,
    "completion_time": 12.3,
    "cost": 0.0067
  }
}
```

**Response (completed):**

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Task finished successfully",
    "files": [
      {
        "source": "https://example.com/report.zip",
        "downloadUrl": "https://blobs.webrun.ai/files/report.zip",
        "filename": "report.zip",
        "timestamp": 1771138379108
      }
    ],
    "network": [
      {
        "id": "tevo9",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://example.com/api/data",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5,
    "cost": 0.0124
  },
  "completedAt": "2024-01-15T10:30:00Z"
}
```

**Response (guardrail triggered):**

```json theme={null}
{
  "success": true,
  "type": "guardrail_trigger",
  "data": {
    "type": "human_input_needed",
    "value": "I need login credentials to proceed"
  }
}
```

**Response (failed):**

```json theme={null}
{
  "success": false,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "failed",
  "error": "Navigation timeout after 30 seconds",
  "code": "NAVIGATION_TIMEOUT",
  "usage": {
    "prompt_tokens": 5000,
    "completion_tokens": 1200,
    "total_tokens": 6200,
    "completion_time": 30.0,
    "cost": 0.0045
  }
}
```

**Error Responses:**

* `404` - Task not found

***

## OpenAI-Compatible Endpoints

### POST /v1/chat/completions

OpenAI-compatible chat completions endpoint. Creates a new session for each request and auto-terminates after completion.

**Authentication:** Required (Bearer token)

<Note>
  The OpenAI-compatible endpoint creates a new session for each request. For multi-task workflows, use the native REST API.
</Note>

**Request Body:**

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

**Response (Non-Streaming):**

```json theme={null}
{
  "id": "chatcmpl-a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "enigma-browser-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I found 5 headings on example.com:\n1. Example Domain\n2. More Information\n3. Contact\n4. About\n5. Privacy Policy"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8450,
    "completion_tokens": 2100,
    "total_tokens": 10550
  },
  "webrun": {
    "sessionId": "a1b2c3d4e5f6",
    "taskId": "x9y8z7w6v5u4",
    "cost": 0.0089
  }
}
```

**Response (Streaming):**

Server-Sent Events (SSE) format:

```
data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"enigma-browser-1","choices":[{"index":0,"delta":{"role":"assistant","content":"I"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"enigma-browser-1","choices":[{"index":0,"delta":{"content":" found"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"enigma-browser-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

**Error Responses:**

* `401` - Invalid API key
* `402` - Insufficient balance
* `429` - Rate limit exceeded
* `503` - No browser instances available
* Guardrail error: `{"error": {"message": "Guardrail triggered: I need login credentials to proceed", "type": "guardrail_error", "code": "guardrail_triggered"}}`

See [OpenAI-Compatible API](/integrations/openai-compatible) for detailed integration guide.

***

### GET /v1/models

List available models for OpenAI-compatible endpoint.

**Authentication:** Required (Bearer token)

**Response:**

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "enigma-browser-1",
      "object": "model",
      "created": 1704067200,
      "owned_by": "enigma"
    }
  ]
}
```

***

## Monitoring Endpoints

### GET /start/health

System health check.

**Response:**

```json theme={null}
{
  "success": true,
  "status": "healthy",
  "instancesAvailable": true,
  "instanceCount": 5,
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

***

## Endpoint Summary

| Endpoint                     | Method | Auth         | Rate Limit       | Description                    |
| ---------------------------- | ------ | ------------ | ---------------- | ------------------------------ |
| `/start/start-session`       | POST   | Required     | 10/min per user  | Create persistent session      |
| `/start/send-message`        | POST   | Required     | 10/min per user  | Send commands to session       |
| `/start/run-task`            | POST   | Required     | 10/min per user  | Execute single task            |
| `/task/:sessionId/:taskId`   | GET    | Not required | None             | Poll for task result           |
| `/v1/chat/completions`       | POST   | Required     | 10/min per user  | OpenAI-compatible chat         |
| `/v1/models`                 | GET    | Required     | None             | List available models          |
| `/files/upload`              | POST   | Required     | 10/min per user  | Upload files for tasks         |
| `/start/health`              | GET    | Not required | None             | System health check            |
| `/profiles`                  | GET    | Required     | 100/15min per IP | List all profiles              |
| `/profiles`                  | POST   | Required     | 100/15min per IP | Create a profile               |
| `/profiles/:id`              | DELETE | Required     | 100/15min per IP | Delete a profile               |
| `/profiles/:id/download`     | GET    | Required     | 100/15min per IP | Download profile data          |
| `/profiles/:id/upload`       | POST   | Required     | 100/15min per IP | Upload profile data            |
| `/cron-jobs`                 | GET    | Required     | —                | List all triggers              |
| `/cron-jobs`                 | POST   | Required     | —                | Create a trigger               |
| `/cron-jobs/:id`             | GET    | Required     | —                | Get a trigger with recent runs |
| `/cron-jobs/:id`             | PUT    | Required     | —                | Update a trigger               |
| `/cron-jobs/:id`             | DELETE | Required     | —                | Delete a trigger               |
| `/cron-jobs/:id/pause`       | POST   | Required     | —                | Pause a trigger                |
| `/cron-jobs/:id/resume`      | POST   | Required     | —                | Resume a paused trigger        |
| `/cron-jobs/:id/trigger`     | POST   | Required     | —                | Manually run a trigger         |
| `/cron-jobs/:id/runs`        | GET    | Required     | —                | List trigger run history       |
| `/cron-jobs/:id/runs/:runId` | GET    | Required     | —                | Get a specific run             |

***

<Accordion title="Related">
  <CardGroup cols={2}>
    <Card title="Parameters Reference" icon="sliders" href="/api-reference/parameters">
      Detailed parameter documentation
    </Card>

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

    <Card title="Triggers" icon="bolt" href="/environments/triggers">
      Schedule recurring tasks with full API reference
    </Card>
  </CardGroup>
</Accordion>