API Reference

Quick Start

Connect your existing Puppeteer, Playwright, or CDP automation to BotCloud by swapping your WebSocket endpoint to wss://cloud.bots.win. No code rewrites — just one line change.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

Authentication

All API endpoints require Bearer token authentication

# All API endpoints require Bearer token authentication
curl -H "Authorization: Bearer your-user-token-here" \
  https://cloud.bots.win/api/quota

GET /api/quota

Check remaining quota before launching jobs

Response: Returns total, used, remaining quota and percentage used

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/quota

GET /api/usage

Get usage statistics for reporting and cost analysis

Response: Returns total sessions, total minutes, and active sessions count

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/usage

GET /api/history

Retrieve session history for audit trails

Parameters: Optional start and end query parameters (ISO 8601 timestamps)

Response: Returns array of session objects with duration and disconnect reasons

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/history

POST /api/user-data

Create a new User Data container for persistent browser state (cookies, localStorage, etc.)

Response: Returns the created User Data ID and timestamp

curl -X POST -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

GET /api/user-data

List all User Data containers for the authenticated user

Response: Returns array of User Data objects with quota information

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

DELETE /api/user-data/:id

Delete a User Data container and release quota

Response: Returns success status

curl -X DELETE -H "Authorization: Bearer your-token" \
  https://cloud.bots.win/api/user-data/udd_abc123xyz789defg

Framework Integration

Puppeteer, PuppeteerSharp, Playwright (Node.js / Python / .NET), raw CDP, Go (chromedp / rod), Java (native WebSocket), and Ruby (Ferrum) all work without code rewrites. Swap wss://cloud.bots.win as your endpoint and pass your token, proxy, and device type as query parameters.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

Billing Model

Subscription plans include monthly browser hours. Once exhausted, additional usage is billed from your prepaid balance at the plan's overage rate.

Connection Errors

These errors happen during connection setup — the session is never created, so it will not appear in /api/history. Check the HTTP status and the message in the response body to handle them.

Disconnect Reasons

Once a session has been opened, it will eventually end with one of the reasons below — recorded in /api/history. Use these codes for error handling and audit trails.