Version

Open an ephemeral session

GET

/api/v1/browser/{protocol}/{browser}

Allocates a browser and upgrades to a websocket in one call: ideal for playwright.chromium.connect(...) or a CDP client. The container is torn down and the session billed as soon as the client disconnects. Authenticate with the token query parameter (your API key secret). Requires the browser.session.create permission.

Operation id: browser.ephemeral
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

Examples

curl -X GET https://webknx.com/api/v1/browser/{protocol}/{browser} \
  -H "Authorization: Bearer $WEBKNX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d 'null' \
  --output qrcode.png

const res = await fetch("https://webknx.com/api/v1/browser/{protocol}/{browser}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.WEBKNX_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(null),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const png = Buffer.from(await res.arrayBuffer());

import os, requests

res = requests.get(
    "https://webknx.com/api/v1/browser/{protocol}/{browser}",
    headers={"Authorization": f"Bearer {os.environ['WEBKNX_SECRET_KEY']}"},
    json=null,
    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/{protocol}/{browser}', NULL)
    ->throw();
file_put_contents('qrcode.png', $res->body());

Request body

null

Responses

200

The connection is upgraded to a websocket carrying the CDP/Playwright protocol.

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.