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:

{
  "profileId": "683a1f2e4b0c1d2e3f4a5b6c",
  "mode": "default",
  "initialTask": {
    "taskDetails": "Go to amazon.com and search for laptops",
    "startingPoint": "https://amazon.com",
    "maxDuration": 300000,
    "maxInputTokens": 100000,
    "maxOutputTokens": 100000,
    "avoidDomains": ["facebook.com"],
    "terminateOnCompletion": false,
    "outputType": "structured_json",
    "outputSchema": {
      "type": "object",
      "properties": {
        "results": { "type": "array" }
      }
    },
    "secrets": [
      {
        "match": "*.amazon.com",
        "fields": { "email": "[email protected]", "password": "pass123" }
      }
    ]
  }
}

The initialTask object contains all task-specific parameters. Use startingPoint to specify the URL where the task should begin. Use profileId (top-level) to attach a browser profile with saved cookies and browser state.

Response (200 OK):

{
  "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 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",
    "taskDetails": "Search for laptops",
    "startingPoint": "https://amazon.com",
    "files": ["abc123..."],
    "maxDuration": 60000,
    "maxInputTokens": 50000,
    "maxOutputTokens": 50000,
    "avoidDomains": ["facebook.com"],
    "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://connect.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",
    "taskDetails": "Username: [email protected], 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:

{
  "profileId": "683a1f2e4b0c1d2e3f4a5b6c",
  "taskDetails": "Search Google for Anthropic",
  "files": ["abc123..."],
  "maxDuration": 300000,
  "maxInputTokens": 100000,
  "maxOutputTokens": 100000,
  "startingUrl": "https://google.com",
  "avoidDomains": [],
  "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://connect.webrun.ai/task/a1b2c3d4e5f6/x9y8z7w6v5u4",
  "message": "Task still running. Poll GET /task/:sessionId/:taskId for result."
}

Error Responses:

400 - Missing taskDetails
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://connect.webrun.ai/files/upload \
  -H "Authorization: Bearer enig_xxx" \
  -F "[email protected]"

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

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

GET /v1/models

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

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

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

Getting Started

Concepts

Usage Guides

Integrations

Profiles

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

Getting Started

Concepts

Usage Guides

Integrations

Profiles

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

Parameters Reference

Response Formats

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