Drive a cloud browser over CDP, and hand it to a person

GET /v1/browser is a WebSocket that speaks the DevTools Protocol (CDP). Point any CDP client at it and you drive a real browser hosted by Spicrawl: open tabs, click, type, run scripts, intercept requests. When a page needs a person, such as a login, a one-time code or a captcha, ask for a live view link. They open it, take control, finish the step, and give control back. Your connection carries on in the same tab with the same cookies.

It needs a key with the browser scope, which new keys do not get by default; grant it deliberately. A session costs 8 credits per started minute and lasts session_ttl seconds (60-900, default 180, at most 15 minutes) or until you disconnect. For scripted page interaction inside one request, use browser actions.

Connect

Mint a single-use connect URL, then open it with your CDP client as its browser WebSocket endpoint:

curl -X POST https://api.spicrawl.com/v1/browser/token \
  -H "Authorization: Bearer $SPICRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_country": "de", "session_ttl": 300}'

{
  "url": "wss://api.spicrawl.com/v1/browser?proxy_country=de&session_ttl=300&token=wbt_...",
  "path": "/v1/browser?proxy_country=de&session_ttl=300&token=wbt_...",
  "expires_at": "2026-11-10T10:31:00Z",
  "expires_in": 60,
  "single_use": true,
  "session_id": "bs4f0c2a9e1d7b38c65a0e9f12"
}

The token (wbt_...) works for one connection, within 60 s, and only with the options it was minted with: editing them in the URL is 400 ERR::REQUEST::INVALID_PARAMETER. Mint a new one for every session. Keep session_id: it is how you ask for the live view later.

This Node.js 22+ script needs no library. It opens example.com and reads its title:

const mint = await fetch('https://api.spicrawl.com/v1/browser/token', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.SPICRAWL_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ session_ttl: 300 }),
}).then((r) => r.json());

const ws = new WebSocket(mint.url);
let id = 0;
const send = (method, params = {}, sessionId) => new Promise((resolve) => {
  const me = ++id;
  ws.addEventListener('message', function on(ev) {
    const msg = JSON.parse(ev.data);
    if (msg.id === me) { ws.removeEventListener('message', on); resolve(msg); }
  });
  ws.send(JSON.stringify({ id: me, method, params, ...(sessionId && { sessionId }) }));
});
await new Promise((r) => ws.addEventListener('open', r));

const { result: { targetId } } = await send('Target.createTarget', { url: 'https://example.com' });
const { result: { sessionId } } = await send('Target.attachToTarget', { targetId, flatten: true });
await new Promise((r) => setTimeout(r, 2000));
const title = await send('Runtime.evaluate', { expression: 'document.title', returnByValue: true }, sessionId);
console.log(title.result.result.value, '| session', mint.session_id);
ws.close();

Any CDP client library connects the same way: pass url as its browser WebSocket endpoint. If your client can set headers on the WebSocket upgrade, you can skip the token and connect to wss://api.spicrawl.com/v1/browser with Authorization: Bearer <key>. That session has no session_id you can address, so it has no live view.

Options

Send them in the token body (or as query parameters on a header-authenticated connect).

Live view and human takeover

While your connection is open, ask for a live view link and send it to a person:

curl -X POST https://api.spicrawl.com/v1/browser/sessions/bs4f0c2a9e1d7b38c65a0e9f12/live \
  -H "Authorization: Bearer $SPICRAWL_API_KEY"

{
  "session_id": "bs4f0c2a9e1d7b38c65a0e9f12",
  "live_view_url": "https://api.spicrawl.com/v1/browser/live#wss%3A%2F%2Fapi.spicrawl.com%2Fv1%2Fbrowser%2Fsessions%2Fbs4f0c2a9e1d7b38c65a0e9f12%2Flive%3Ftoken%3Dwbv_...",
  "live_url": "wss://api.spicrawl.com/v1/browser/sessions/bs4f0c2a9e1d7b38c65a0e9f12/live?token=wbv_...",
  "expires_in": 60,
  "single_use": true
}

curl https://api.spicrawl.com/v1/browser/sessions/bs4f0c2a9e1d7b38c65a0e9f12 \
  -H "Authorization: Bearer $SPICRAWL_API_KEY"
# {"session_id":"bs4f0c2a9e1d7b38c65a0e9f12","status":"running","controller":"agent","expires_at":"2026-11-10T10:35:00Z"}

You can also flip control yourself: POST /v1/browser/sessions/{id}/takeover hands it to the person, and POST /v1/browser/sessions/{id}/release gives it back to your connection. Both answer like the GET.

• Not billed separately. Watching rides the session's per-minute price. The live view ends when the session does.
• Who can see it. The routes need your key and the browser scope. Another organization's session, an unknown id and a closed session are all 404 ERR::REQUEST::NOT_FOUND. The viewer token (wbv_ and 64 hex characters) is stored only as a hash. The page keeps it in the URL fragment, which a browser never sends to a server, and removes it from the address bar on load.
• What the viewer can do. Stream the page and, while holding control, send input. It cannot run scripts, read cookies or navigate by URL.
• From an AI agent. The MCP tools spicrawl_browser_live_view and spicrawl_browser_control wrap these routes.

What is refused

A few commands would let a session leave its assigned exit or act on the browser as a whole. They are answered with a CDP error and never reach the browser: a per-context proxy (Target.createBrowserContext with proxyServer), Browser.close and Browser.crash, SystemInfo.*, Target.exposeDevToolsProtocol, Target.sendMessageToTarget (use flat sessions, sessionId), and navigation to any scheme other than http, https, data and about:blank. Downloads are always denied. Every request the browser makes goes through Spicrawl's proxy with the same private-network guard as /v1/scrape.

Limits and errors

Errors before the WebSocket upgrade are ordinary problem responses; after it, a session ends by closing the connection.

Related

• Browser actions: scripted clicks and typing inside one /v1/scrape request, no connection to hold.
• Sessions and logins: keep cookies across scrapes.
• MCP server: the same browser from an AI agent.