Skip to content
APIs Pricing Docs Guides Log in Start free

Create a browser session

POST
/api/v1/browser/session

Allocates a browser container and returns a reconnectable session id. Requires the browser.session.create permission. The session (and its container) stay alive across client disconnects until you DELETE it, so you can reconnect with the same id.

Operation id
browser.session.create
Authentication
Bearer API key
Required permission
browser.session.create
Price
1 credit per successful request
Rate limit
120 requests per minute per key, 600 per workspace

Request

FieldTypeRequiredDescription
protocol string
cdp | playwright		 Yes Wire protocol to speak to the browser.
browser string
chrome | chromium | edge | opera | firefox		 Yes Browser engine. Not every engine is available on every protocol.

Examples

curl -X POST https://webknx.com/api/v1/browser/session \
  -H "Authorization: Bearer $WEBKNX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"browser":"chrome","protocol":"cdp"}' \
  --output qrcode.png
const res = await fetch("https://webknx.com/api/v1/browser/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEBKNX_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"browser":"chrome","protocol":"cdp"}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const png = Buffer.from(await res.arrayBuffer());
import os, requests

res = requests.post(
    "https://webknx.com/api/v1/browser/session",
    headers={"Authorization": f"Bearer {os.environ['WEBKNX_SECRET_KEY']}"},
    json={"browser":"chrome","protocol":"cdp"},
    timeout=15,
)
res.raise_for_status()
open("qrcode.png", "wb").write(res.content)
$res = Http::withToken(getenv('WEBKNX_SECRET_KEY'))
    ->post('https://webknx.com/api/v1/browser/session', array (
  'browser' => 'chrome',
  'protocol' => 'cdp',
))
    ->throw();
file_put_contents('qrcode.png', $res->body());

Request body

{
    "browser": "chrome",
    "protocol": "cdp"
}

Responses

200
The created session. application/json

{
    "session_id": "Ab3dEf6hIj9lMn2p"
}

400
The request or the protocol/browser combination is invalid. application/json

{
    "code": "invalid_browser",
    "message": "Unsupported protocol/browser combination."
}

401
Authentication failed. application/json

{
    "code": "unauthorized",
    "message": "Authentication failed."
}

402
The workspace has no remaining credits. application/json

{
    "code": "insufficient_credits",
    "message": "The workspace has no remaining credits."
}

403
The API key lacks the required browser permission. application/json

{
    "code": "forbidden",
    "message": "The API key lacks the required browser permission."
}

See errors and retries for how to handle each error code.