API overview
New API documentation
The full endpoint reference now lives at doc.virtualbrowser.cc (Chinese only for now). This page keeps the local client setup and authentication notes.
VirtualBrowser exposes an HTTP API from the running desktop client. This is not the website login API or the IPGeo query service. Behavior was checked against the client source on 2026-11-04; Apifox is an additional reference; see the complete endpoint index.
1. Enable the service
- Open the client and sign in with an active Pro membership.
- Open API and copy its service address and api-key.
- Keep the client running. For unattended startup, see CLI mode.
The base URL is http://127.0.0.1:{port} (or the address shown in the client). The port is dynamically allocated; 9000 is only an example. The port returned by launchBrowser is a different port, for browser CDP automation.
2. Authenticate
Send the local API key in the request header, not a website login token or an IPGeo key:
api-key: YOUR_API_KEY
Content-Type: application/jsonGET business parameters go in the query string. POST business parameters go in a JSON request body. Do not put the key in the URL.
Header required by current clients
Some Apifox pages mark api-key as optional or do not mark it as required. Current clients apply shared authentication to these routes, so all examples include the header. The key in a published example is not a usable credential; copy your own from the client.
3. First requests
The cURL examples use Bash line continuations. On Windows, use curl.exe with a single-line command or use PowerShell:
$base = 'http://127.0.0.1:9000' # Replace with the API screen address
$headers = @{ 'api-key' = 'YOUR_API_KEY' }
Invoke-RestMethod -Uri "$base/api/getBrowserList" -Headers $headers
$body = @{ id = 1 } | ConvertTo-Json
$launch = Invoke-RestMethod -Method Post -Uri "$base/api/launchBrowser" -Headers $headers -ContentType 'application/json' -Body $body -TimeoutSec 60
if (-not $launch.success) { throw $launch.error }
$launch.data.debuggingPortFor CDP, connect Playwright/Puppeteer to http://127.0.0.1:{debuggingPort}, not to the API port. See Playwright integration.
4. Parse responses
Most successful requests use:
{ "success": true, "data": {} }data is not always present and is not always an object. It may be an array, a boolean, or a profile object. Some endpoints only return success, or include message or other top-level fields.
- Launch: CDP port at data.debuggingPort.
- Core versions: data array, plus top-level total and majors.
- Cookies: data is a cookie array, not cookie.jsonStr.
- Running state: Apifox defines a raw boolean; current clients return a success/data wrapper. The endpoint page includes compatible parsing.
Failures commonly use:
{ "success": false, "error": "Error message" }Check both HTTP status and the body. Do not treat HTTP 200 alone as success, and do not require data on every successful response. See Errors & troubleshooting.
5. Calling safely
- Use IDs from the list response rather than assuming they are sequential.
- Query available cores before choosing a major version. Example versions are not defaults.
- Close profiles before reading/writing cookies or deleting data. Back up before destructive actions.
- Use bounded concurrency. After a launch timeout, check running profiles before retrying.
- Keep keys and saved-account passwords out of public logs. Only allow trusted access to the API service.
- Window arrangement is Windows-only. An empty body arranges all running profiles.
Further reading
Security boundary and access logs
The current client HTTP service binds to 0.0.0.0; localhost is the recommended local address, not a guarantee that LAN or other networks cannot connect. The service uses HTTP. Restrict sources with a firewall; use a trusted encrypted channel for remote access and do not expose the port directly to the internet. The client API key differs from the IPGeo key; refreshing it invalidates the old value.
Account APIs may return plaintext passwords, and cookies, proxy authentication, full profile data and MCP page content may be sensitive. Never publish real requests, responses or screenshots. Responses include X-Request-Id, which can be correlated with api-access.log; the default Windows path is %APPDATA%/VirtualBrowser/User Data/api-access.log, rotated to .1 after roughly 20 MiB. Log masking does not cover every field: remove email, usernames, password_value, cookies, keys and proxy credentials before sharing.
The current POST JSON body limit is 10 MiB; exceeding it may return HTTP 413, and the response is not necessarily the API JSON error shape.



