Quickstart

npm install patchright

pip install patchright requests

import { chromium } from "patchright";

const API = "https://api.driver.dev";
const headers = {
  Authorization: `Bearer ${process.env.DRIVER_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Create a session. Every field is optional; this one asks for a US browser for ten minutes.
const res = await fetch(`${API}/v1/browser/session`, {
  method: "POST",
  headers,
  body: JSON.stringify({ country: "US", duration: 600 }),
});
if (!res.ok) throw new Error(`Driver ${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const session = await res.json();

try {
  // 2. Connect over CDP and reuse the browser's own context and tab.
  const browser = await chromium.connectOverCDP(session.cdpUrl);
  try {
    const context = browser.contexts()[0] ?? (await browser.newContext());
    const page = context.pages()[0] ?? (await context.newPage());

    // 3. Do the work.
    await page.goto("https://example.com");
    console.log(await page.title());
  } finally {
    await browser.close(); // ends your connection; the session is still running
  }
} finally {
  // 4. Stop the session. This is what ends billing.
  await fetch(`${API}/v1/browser/session?sessionId=${session.sessionId}`, {
    method: "DELETE",
    headers,
  });
}

import os
import requests
from patchright.sync_api import sync_playwright

API = "https://api.driver.dev"
headers = {"Authorization": f"Bearer {os.environ['DRIVER_API_KEY']}"}

# 1. Create a session. Every field is optional; this one asks for a US browser for ten minutes.
session = requests.post(f"{API}/v1/browser/session", headers=headers, json={"country": "US", "duration": 600})
session.raise_for_status()
session = session.json()

try:
    # 2. Connect over CDP and reuse the browser's own context and tab.
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(session["cdpUrl"])
        context = browser.contexts[0] if browser.contexts else browser.new_context()
        page = context.pages[0] if context.pages else context.new_page()

        # 3. Do the work.
        page.goto("https://example.com")
        print(page.title())
        browser.close()
finally:
    # 4. Stop the session. This is what ends billing.
    requests.delete(
        f"{API}/v1/browser/session",
        headers=headers,
        params={"sessionId": session["sessionId"]},
    )

# Create
curl -s -X POST https://api.driver.dev/v1/browser/session \
  -H "Authorization: Bearer $DRIVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","duration":600}'
# → {"sessionId":"…","status":"active","cdpUrl":"wss://…", …}

# Stop
curl -s -X DELETE "https://api.driver.dev/v1/browser/session?sessionId=$SESSION_ID" \
  -H "Authorization: Bearer $DRIVER_API_KEY"