Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview

Click, double-click, drag, type, press keys or scroll on the sandbox's desktop

Runs one mouse or keyboard action on the X11 desktop and returns once it has been sent. Take a screenshot to see its effect. Fields that do not belong to the action’s type are rejected.

While a person viewing the desktop has taken control of it, actions are refused with 409 desktop_controlled, whose error.control says who has it and until when; GET .../desktop/control tells the same. Retry once they hand it back or it lapses.

POST/v1/sandboxes/{sandbox}/computer/actions
Authorization
AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Path parameters
sandboxstringrequired

Sandbox ID (sbx_...) or name.

Request body
requiredapplication/json
typeComputerActionTyperequired

click: click button at (x, y). double_click: double-click button at (x, y). drag: press the left button at (x, y), move to (to_x, to_y) and release. type: type text as keystrokes. key: press keys. scroll: scroll amount wheel clicks in direction with the pointer at (x, y).

Allowed:clickdouble_clickdragtypekeyscroll
xinteger

Pointer x (click, double_click, scroll; start of a drag).

min 0 · max 1919
yinteger

Pointer y (click, double_click, scroll; start of a drag).

min 0 · max 1079
to_xinteger

End x of a drag.

min 0 · max 1919
to_yinteger

End y of a drag.

min 0 · max 1079
buttonstring

Mouse button (click, double_click).

default: "left"
Allowed:leftmiddleright
textstring

Text to type (type), including newlines. Typed at about 80 characters per second.

min length 1 · max length 10000
keysstring

Keys to press (key): X keysym names joined with + for a chord, several separated by spaces, for example Return, ctrl+l, ctrl+shift+t or Escape Tab Tab. Every component must resolve to an X keysym in the guest; command names are not keys.

matches ^[A-Za-z0-9_]+(\+[A-Za-z0-9_]+)*( [A-Za-z0-9_]+(\+[A-Za-z0-9_]+)*){0,31}$
directionstring

Scroll direction (scroll).

Allowed:updownleftright
amountinteger

Wheel clicks to scroll (scroll).

min 1 · max 50 · default: 3
Responses
204

Done.

429

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.

errorobjectrequired
Show properties
codestringrequired

Stable 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).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only 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.

default

Error.

errorobjectrequired
Show properties
codestringrequired

Stable 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).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only 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.

Request
curl -X POST 'https://api.pols.so/v1/sandboxes/string/computer/actions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "click",
  "x": 0,
  "y": 0,
  "to_x": 0,
  "to_y": 0,
  "button": "left",
  "text": "string",
  "keys": "ctrl+l",
  "direction": "up",
  "amount": 3
}'
Response
Done.