Connect to the sandbox's Chrome DevTools Protocol endpoint (WebSocket)
A WebSocket upgrade. Once connected, this is Chrome’s browser-level
CDP endpoint (/devtools/browser/<id>): messages are relayed
unchanged in both directions. Chrome is started on the sandbox’s
desktop if it is not running yet, so the browser is also visible in
screenshots and can be driven with /computer/actions.
Authenticate with the API key (Authorization: Bearer pols_..., for
example Playwright’s connectOverCDP(url, { headers })), or with the
token query parameter of a URL from POST /v1/sandboxes/{sandbox}/browser/cdp. Errors before the upgrade are
returned as JSON.
/v1/sandboxes/{sandbox}/browser/cdpAuthorizationBearer token · headerrequiredOrg-scoped API key, pols_....
tokenAPI key · queryrequiredShort-lived, sandbox-scoped token from POST /v1/sandboxes/{sandbox}/browser/cdp. Only accepted to connect to that sandbox's CDP endpoint.
sandboxstringrequiredSandbox ID (sbx_...) or name.
Switched to the WebSocket protocol.
Rate limited (rate_limited): too many requests or failed
authentications from this address, too many requests or
lifecycle calls for this org, or too many of its exec, file,
computer and CDP calls in progress at once. Retry after
Retry-After seconds.
errorobjectrequiredShow propertiesHide properties
codestringrequiredStable machine-readable code: bad_request (400),
unauthorized (401), insufficient_credit (402, no
credit left to start a sandbox), forbidden (403),
quota_exceeded (403), trial_limit (403, beyond what a
trial org may run), not_found (404), conflict (409),
billing_details_required (409, save the billing details
before topping up), topup_not_available (409, the org
cannot top up as it would be taxed; the message says why),
withdrawal_consent_required (409, a consumer orders a
top-up or the subscription only with withdrawal_consent),
desktop_controlled (409, a person viewing the desktop has
taken control of it, see control), rate_limited (429,
see Retry-After), trial_capacity
(429, all trial capacity in use; retry after
Retry-After), host_capacity (429, the host is short of
memory right now, so nothing new starts there; retry after
Retry-After), internal (500),
runtime_error (502, the sandbox host failed),
payment_provider_error (502, Mollie could not be
reached or refused a payment),
unavailable (503, the feature is not configured on this
deployment), waking (503, the sandbox is still waking
from standby or booting; retry), timeout (504, or 408 when a request
body stalls).
messagestringrequiredcontrolDesktopControlWho has control of a sandbox's desktop. In an error, it is present
only with code desktop_controlled.
Show propertiesHide properties
heldbooleanrequiredSomeone viewing the desktop has taken control of it.
holderstringOnly when held; their name as the desktop's viewers see it, their user's name or else their API key's.
sincestring<date-time>Only when held; when they took control.
expires_atstring<date-time>Only when held; when control lapses unless they use the desktop before.
Error.
errorobjectrequiredShow propertiesHide properties
codestringrequiredStable machine-readable code: bad_request (400),
unauthorized (401), insufficient_credit (402, no
credit left to start a sandbox), forbidden (403),
quota_exceeded (403), trial_limit (403, beyond what a
trial org may run), not_found (404), conflict (409),
billing_details_required (409, save the billing details
before topping up), topup_not_available (409, the org
cannot top up as it would be taxed; the message says why),
withdrawal_consent_required (409, a consumer orders a
top-up or the subscription only with withdrawal_consent),
desktop_controlled (409, a person viewing the desktop has
taken control of it, see control), rate_limited (429,
see Retry-After), trial_capacity
(429, all trial capacity in use; retry after
Retry-After), host_capacity (429, the host is short of
memory right now, so nothing new starts there; retry after
Retry-After), internal (500),
runtime_error (502, the sandbox host failed),
payment_provider_error (502, Mollie could not be
reached or refused a payment),
unavailable (503, the feature is not configured on this
deployment), waking (503, the sandbox is still waking
from standby or booting; retry), timeout (504, or 408 when a request
body stalls).
messagestringrequiredcontrolDesktopControlWho has control of a sandbox's desktop. In an error, it is present
only with code desktop_controlled.
Show propertiesHide properties
heldbooleanrequiredSomeone viewing the desktop has taken control of it.
holderstringOnly when held; their name as the desktop's viewers see it, their user's name or else their API key's.
sincestring<date-time>Only when held; when they took control.
expires_atstring<date-time>Only when held; when control lapses unless they use the desktop before.