Référence API

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();

Authentification

Tous les endpoints API nécessitent une authentification par token Bearer

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

GET /api/quota

Vérifier le quota restant avant de lancer des travaux

Response: Retourne le quota total, utilisé, restant et le pourcentage utilisé

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

GET /api/usage

Obtenir les statistiques d'utilisation pour les rapports et l'analyse des coûts

Response: Retourne le nombre total de sessions, les minutes totales et le nombre de sessions actives

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

GET /api/history

Récupérer l'historique des sessions pour les pistes d'audit

Parameters: Paramètres de requête optionnels de début et fin (timestamps ISO 8601)

Response: Retourne un tableau d'objets de session avec durée et raisons de déconnexion

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

POST /api/user-data

Créer un nouveau conteneur de données utilisateur pour l'état persistant du navigateur (cookies, localStorage, etc.)

Response: Retourne l'ID et l'horodatage des données utilisateur créées

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

GET /api/user-data

Lister tous les conteneurs de données utilisateur pour l'utilisateur authentifié

Response: Retourne un tableau d'objets de données utilisateur avec informations de quota

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

DELETE /api/user-data/:id

Supprimer un conteneur de données utilisateur et libérer le quota

Response: Retourne le statut de succès

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();

Modèle de facturation

Les plans d'abonnement incluent des heures de navigateur mensuelles. Une fois épuisées, l'utilisation supplémentaire est facturée depuis votre solde prépayé au tarif overage du plan.

Erreurs de connexion

Ces erreurs surviennent lors de l'établissement de la connexion — la session n'est jamais créée et n'apparaît donc pas dans /api/history. Vérifiez le statut HTTP et le message dans le corps de la réponse pour les gérer.

Raisons de déconnexion

Une fois une session ouverte, elle se terminera éventuellement par l'une des raisons ci-dessous — enregistrée dans /api/history. Utilisez ces codes pour la gestion des erreurs et les pistes d'audit.