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:

{
  "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" }
      }
    ]
  }
}

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 with saved cookies, browser state, and persistent files. Use policyId (top-level) to enforce automation policy rules on agent actions. Use proxy (top-level) to route the session through a proxy server.

Response (200 OK):

{
  "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 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:

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

Supported Action Types:

actionType: newTask

Start a new task. Returns taskId for polling.

{
  "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):

{
  "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):

{
  "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.

{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "state",
    "newState": "pause | resume | stop | terminate"
  }
}

Response:

{
  "success": true,
  "message": "Message sent successfully"
}

actionType: interaction

Manual browser control. Returns immediate success.

{
  "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:

{
  "success": true,
  "message": "Message sent successfully"
}

actionType: guardrail

Respond to guardrail trigger. Returns immediate success.

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

Response:

{
  "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

terminateOnCompletion is automatically set to true for this endpoint. The session will close after task completion.

Request Body:

{
  "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):

{
  "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):

{
  "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:

curl -X POST https://api.webrun.ai/files/upload \
  -H "Authorization: Bearer wr_xxx" \
  -F "files=@document.pdf"

Response (200 OK):

{
  "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 for complete examples.

Task Endpoints

GET /task/:sessionId/:taskId

Poll for task result. Path Parameters:

sessionId - Session identifier
taskId - Task identifier

Response (still running):

{
  "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):

{
  "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):

{
  "success": true,
  "type": "guardrail_trigger",
  "data": {
    "type": "human_input_needed",
    "value": "I need login credentials to proceed"
  }
}

Response (failed):

{
  "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)

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

Request Body:

{
  "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):

{
  "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 for detailed integration guide.

GET /v1/models

List available models for OpenAI-compatible endpoint. Authentication: Required (Bearer token) Response:

{
  "object": "list",
  "data": [
    {
      "id": "webrun-browser-1",
      "object": "model",
      "created": 1704067200,
      "owned_by": "webrun"
    }
  ]
}

Monitoring Endpoints

GET /start/health

System health check. Response:

{
  "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

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Base URL

Session Endpoints

POST /start/start-session

POST /start/send-message

actionType: newTask

actionType: state

actionType: interaction

actionType: guardrail

POST /start/run-task

File Upload Endpoints

POST /files/upload

Task Endpoints

GET /task/:sessionId/:taskId

OpenAI-Compatible Endpoints

POST /v1/chat/completions

GET /v1/models

Monitoring Endpoints

GET /start/health

Endpoint Summary

​Base URL

​Session Endpoints

​POST /start/start-session

​POST /start/send-message

​actionType: newTask

​actionType: state

​actionType: interaction

​actionType: guardrail

​POST /start/run-task

​File Upload Endpoints

​POST /files/upload

​Task Endpoints

​GET /task/:sessionId/:taskId

​OpenAI-Compatible Endpoints

​POST /v1/chat/completions

​GET /v1/models

​Monitoring Endpoints

​GET /start/health

​Endpoint Summary

Parameters Reference

Response Formats

Triggers

Base URL

Session Endpoints

POST /start/start-session

POST /start/send-message

actionType: newTask

actionType: state

actionType: interaction

actionType: guardrail

POST /start/run-task

File Upload Endpoints

POST /files/upload

Task Endpoints

GET /task/:sessionId/:taskId

OpenAI-Compatible Endpoints

POST /v1/chat/completions

GET /v1/models

Monitoring Endpoints

GET /start/health

Endpoint Summary