> ## 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://api.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://api.webrun.ai",
  "streaming": {
    "webRTCURL": "https://a1b2c3d4e5f6.webrun.ai/whep",
    "webViewURL": "https://a1b2c3d4e5f6.webrun.ai",
    "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://api.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://api.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://api.webrun.ai/files/upload \
  -H "Authorization: Bearer wr_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": "webrun-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": "webrun-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":"webrun-browser-1","choices":[{"index":0,"delta":{"role":"assistant","content":"I"},"finish_reason":null}]}

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

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"webrun-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": "webrun-browser-1",
      "object": "model",
      "created": 1704067200,
      "owned_by": "webrun"
    }
  ]
}
```

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.