REST API Integration

When to Use REST API

The REST API is ideal for:

Serverless environments (AWS Lambda, Vercel, Cloudflare Workers)
Simple integrations where you don’t need real-time events
Stateless workflows that poll for results
Backend services that trigger automation tasks
Workflow automation (n8n, Make.com, Zapier)

Choose WebSocket instead if you need:

Live agent thoughts and reasoning
Sub-second event notifications
Real-time UI updates

Authentication

All API requests require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Get your API key at webrun.ai/settings Base URL:

https://api.webrun.ai

Basic Patterns

Pattern 1: Single Task (run-task)

The simplest pattern for one-off tasks. Session auto-terminates after completion.

curl -X POST https://api.webrun.ai/start/run-task \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "task": {
      "prompt": "Go to google.com and search for Anthropic"
    }
  }'

Response (completed within 50 seconds):

{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Successfully searched for Anthropic on Google",
    "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 after 50 seconds):

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

Most browser tasks complete in 10-40 seconds. The API waits up to 50 seconds before responding, so typical requests return results immediately: no polling required.

Pattern 2: Multi-Task Session

For workflows that require multiple sequential tasks in the same browser session. Step 1: Create persistent session

curl -X POST https://api.webrun.ai/start/start-session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "mode": "default",
    "task": {
      "prompt": "Go to amazon.com",
      "startingUrl": "https://amazon.com"
    }
  }'

Response:

{
  "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 }
  },
  "expiresIn": 300000,
  "balance": 12.50
}

Step 2: Send follow-up task

curl -X POST https://api.webrun.ai/start/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sessionId": "a1b2c3d4e5f6",
    "message": {
      "actionType": "newTask",
      "newState": "start",
      "prompt": "Search for wireless keyboards",
      "terminateOnCompletion": true
    }
  }'

Cost Tip: Set terminateOnCompletion: true on your last task to auto-close the session and avoid idle charges. Sessions remain billable until terminated or timed out.

Pattern 3: Polling for Results

When a task returns status: "pending", poll until completion:

async function runTask(prompt, apiKey) {
  const response = await fetch("https://api.webrun.ai/start/run-task", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({ task: { prompt } })
  });

  const data = await response.json();

  // Inline result - return immediately
  if (data.status === "complete") {
    return data.result;
  }

  // Pending - poll for result
  if (data.status === "pending") {
    return await pollForResult(data.sessionId, data.taskId, apiKey);
  }

  throw new Error(data.message || "Task failed");
}

async function pollForResult(sessionId, taskId, apiKey) {
  const maxAttempts = 60; // 2 minutes max
  const interval = 2000; // Poll every 2 seconds

  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(
      `https://api.webrun.ai/task/${sessionId}/${taskId}`,
      { headers: { "Authorization": `Bearer ${apiKey}` } }
    );

    const data = await res.json();

    if (data.type === "task_completed") return data;
    if (data.type === "guardrail_trigger") return data;
    if (!data.success && data.status === "failed") throw new Error(data.error);

    // Still running - wait and retry
    await new Promise(r => setTimeout(r, interval));
  }

  throw new Error("Task timeout after 2 minutes");
}

// Usage
const result = await runTask("Search Google for Anthropic", "wr_xxx");
console.log(result.data.message);
console.log(`Cost: $${result.usage.cost}`);

Complete Examples

Example 1: Simple Task Execution

const API_KEY = "wr_xxxxxxxxxxxx";

async function searchGoogle(query) {
  const response = await fetch("https://api.webrun.ai/start/run-task", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      task: {
        prompt: `Search Google for "${query}" and summarize the first result`
      }
    })
  });

  const data = await response.json();

  if (data.status === "complete") {
    return data.result.data.message;
  } else if (data.status === "pending") {
    // Poll for result
    const result = await pollForResult(data.sessionId, data.taskId, API_KEY);
    return result.data.message;
  }

  throw new Error(data.message || "Task failed");
}

// Usage
const summary = await searchGoogle("Anthropic Claude");
console.log(summary);

Example 2: Multi-Step Workflow

const API_KEY = "wr_xxxxxxxxxxxx";
const BASE = "https://api.webrun.ai";

async function amazonProductResearch(productName) {
  // 1. Create session
  const session = await fetch(`${BASE}/start/start-session`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      mode: "default",
      task: {
        prompt: "Go to amazon.com",
        startingUrl: "https://amazon.com"
      }
    })
  }).then(r => r.json());

  const sessionId = session.sessionId;

  // 2. Search for product
  const searchTask = await fetch(`${BASE}/start/send-message`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      sessionId,
      message: {
        actionType: "newTask",
        newState: "start",
        prompt: `Search for "${productName}" and list the top 3 results with prices`
      }
    })
  }).then(r => r.json());

  // Poll if needed
  let searchResult;
  if (searchTask.pending) {
    searchResult = await pollForResult(sessionId, searchTask.taskId, API_KEY);
  } else {
    searchResult = searchTask.result;
  }

  console.log("Search results:", searchResult.data.message);

  // 3. Add first item to cart
  const cartTask = await fetch(`${BASE}/start/send-message`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      sessionId,
      message: {
        actionType: "newTask",
        newState: "start",
        prompt: "Add the first product to cart",
        terminateOnCompletion: true // Auto-close session
      }
    })
  }).then(r => r.json());

  // Poll if needed
  let cartResult;
  if (cartTask.pending) {
    cartResult = await pollForResult(sessionId, cartTask.taskId, API_KEY);
  } else {
    cartResult = cartTask.result;
  }

  return {
    searchResults: searchResult.data.message,
    cartStatus: cartResult.data.message
  };
}

// Usage
const results = await amazonProductResearch("wireless keyboard");
console.log(results);

Example 3: Using a Proxy

Route traffic through a proxy for geographic targeting or IP management. The proxy field is top-level, alongside environmentId:

const API_KEY = "wr_xxxxxxxxxxxx";

// WebRun-managed proxy (specify country)
const response = await fetch("https://api.webrun.ai/start/run-task", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`
  },
  body: JSON.stringify({
    task: {
      prompt: "Check product prices on amazon.co.uk",
      startingUrl: "https://amazon.co.uk"
    },
    proxy: {
      source: "WebRun",
      country: "GB"
    }
  })
});

const data = await response.json();
console.log(data);

See the Proxies guide for custom proxy configuration and best practices.

Example 4: Using an Environment

Attach an environment to reuse saved cookies and login sessions across tasks:

const API_KEY = "wr_xxxxxxxxxxxx";

async function runWithEnvironment(environmentId, prompt) {
  const response = await fetch("https://api.webrun.ai/start/run-task", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      environmentId,
      task: { prompt }
    })
  });

  return response.json();
}

// First run: log in and save cookies to the environment's profile
await runWithEnvironment("<ENV_ID>", "Go to amazon.com and log in");

// Subsequent runs: environment has saved cookies, no login needed
const result = await runWithEnvironment(
  "<ENV_ID>",
  "Go to amazon.com and check my recent orders"
);
console.log(result);

Example 5: Authenticated Task with Secrets

Use secrets to provide credentials upfront so the agent can authenticate without guardrail interruptions:

async function loginAndExtractWithSecrets(url) {
  const BASE = "https://api.webrun.ai";
  const API_KEY = "wr_xxxxxxxxxxxx";

  const session = await fetch(`${BASE}/start/start-session`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      mode: "default",
      task: {
        prompt: `Go to ${url}, log in, and extract all user data from the dashboard`,
        startingUrl: url,
        terminateOnCompletion: true,
        secrets: [
          {
            match: `*.${new URL(url).hostname}`,
            fields: {
              email: process.env.SITE_EMAIL,
              password: process.env.SITE_PASSWORD
            }
          }
        ]
      }
    })
  }).then(r => r.json());

  // Poll for result, no guardrail handling needed
  const taskId = session.taskId || session.sessionId;
  return await pollForResult(session.sessionId, taskId, API_KEY);
}

Example 6: Handling Guardrails

async function loginAndExtractData(url, credentials) {
  const BASE = "https://api.webrun.ai";
  const API_KEY = "wr_xxxxxxxxxxxx";

  // Create session with login task
  const session = await fetch(`${BASE}/start/start-session`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      mode: "default",
      task: {
        prompt: `Go to ${url} and log in`,
        startingUrl: url
      }
    })
  }).then(r => r.json());

  const sessionId = session.sessionId;

  // Start login task
  const loginTask = await fetch(`${BASE}/start/send-message`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      sessionId,
      message: {
        actionType: "newTask",
        newState: "start",
        prompt: "Log in to the website"
      }
    })
  }).then(r => r.json());

  // Poll for result
  const taskId = loginTask.taskId;
  let result = await pollForResult(sessionId, taskId, API_KEY);

  // Handle guardrail if triggered
  if (result.type === "guardrail_trigger") {
    console.log("Guardrail:", result.data.value);

    // Provide credentials
    await fetch(`${BASE}/start/send-message`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        sessionId,
        message: {
          actionType: "guardrail",
          prompt: `Username: ${credentials.username}, Password: ${credentials.password}`,
          newState: "resume"
        }
      })
    });

    // Continue polling
    result = await pollForResult(sessionId, taskId, API_KEY);
  }

  // Extract data after login
  const extractTask = await fetch(`${BASE}/start/send-message`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      sessionId,
      message: {
        actionType: "newTask",
        newState: "start",
        prompt: "Extract all user data from the dashboard",
        terminateOnCompletion: true
      }
    })
  }).then(r => r.json());

  if (extractTask.pending) {
    return await pollForResult(sessionId, extractTask.taskId, API_KEY);
  }

  return extractTask.result;
}

Session Control

Control task execution with state commands:

Pause Task

curl -X POST https://api.webrun.ai/start/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sessionId": "a1b2c3d4e5f6",
    "message": { "actionType": "state", "newState": "pause" }
  }'

Resume Task

curl -X POST https://api.webrun.ai/start/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sessionId": "a1b2c3d4e5f6",
    "message": { "actionType": "state", "newState": "resume" }
  }'

Stop Task

curl -X POST https://api.webrun.ai/start/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sessionId": "a1b2c3d4e5f6",
    "message": { "actionType": "state", "newState": "stop" }
  }'

Terminate Session

curl -X POST https://api.webrun.ai/start/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sessionId": "a1b2c3d4e5f6",
    "message": { "actionType": "state", "newState": "terminate" }
  }'

Error Handling

All errors follow this format:

{
  "success": false,
  "message": "Human-readable error message",
  "code": "ERROR_CODE"
}

Common Error Codes

Status	Code	Solution
400	`INVALID_PARAMS`	Check request parameters
401	`INVALID_API_KEY`	Verify API key is correct
402	`INSUFFICIENT_BALANCE`	Add funds to account
404	`SESSION_NOT_FOUND`	Session expired or invalid
429	`RATE_LIMIT_EXCEEDED`	Wait before retrying
503	`NO_INSTANCES_AVAILABLE`	Retry in a few moments

Error Handling Example

async function executeTaskWithRetry(prompt, apiKey, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch("https://api.webrun.ai/start/run-task", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${apiKey}`
        },
        body: JSON.stringify({ task: { prompt } })
      });

      const data = await response.json();

      if (!response.ok) {
        // Handle specific error codes
        if (response.status === 503) {
          console.log(`Attempt ${attempt}: No instances available, retrying...`);
          await new Promise(r => setTimeout(r, 2000 * attempt));
          continue;
        }

        if (response.status === 429) {
          console.log(`Attempt ${attempt}: Rate limited, waiting...`);
          await new Promise(r => setTimeout(r, 5000 * attempt));
          continue;
        }

        throw new Error(`HTTP ${response.status}: ${data.message}`);
      }

      return data;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      console.error(`Attempt ${attempt} failed:`, error.message);
    }
  }
}

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

When to Use REST API

Authentication

Basic Patterns

Pattern 1: Single Task (run-task)

Pattern 2: Multi-Task Session

Pattern 3: Polling for Results

Complete Examples

Example 1: Simple Task Execution

Example 2: Multi-Step Workflow

Example 3: Using a Proxy

Example 4: Using an Environment

Example 5: Authenticated Task with Secrets

Example 6: Handling Guardrails

Session Control

Pause Task

Resume Task

Stop Task

Terminate Session

Error Handling

Common Error Codes

Error Handling Example

​When to Use REST API

​Authentication

​Basic Patterns

​Pattern 1: Single Task (run-task)

​Pattern 2: Multi-Task Session

​Pattern 3: Polling for Results

​Complete Examples

​Example 1: Simple Task Execution

​Example 2: Multi-Step Workflow

​Example 3: Using a Proxy

​Example 4: Using an Environment

​Example 5: Authenticated Task with Secrets

​Example 6: Handling Guardrails

​Session Control

​Pause Task

​Resume Task

​Stop Task

​Terminate Session

​Error Handling

​Common Error Codes

​Error Handling Example

WebSocket Integration

API Reference

Environments

File Uploads

When to Use REST API

Authentication

Basic Patterns

Pattern 1: Single Task (run-task)

Pattern 2: Multi-Task Session

Pattern 3: Polling for Results

Complete Examples

Example 1: Simple Task Execution

Example 2: Multi-Step Workflow

Example 3: Using a Proxy

Example 4: Using an Environment

Example 5: Authenticated Task with Secrets

Example 6: Handling Guardrails

Session Control

Pause Task

Resume Task

Stop Task

Terminate Session

Error Handling

Common Error Codes

Error Handling Example