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.

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), forbidden (403), quota_exceeded (403), not_found (404), conflict (409), rate_limited (429, see Retry-After), internal (500), runtime_error (502, the sandbox host failed), unavailable (503, the feature is not configured on this deployment), timeout (504, or 408 when a request body stalls).

messagestringrequired

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

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
}'

const response = await fetch("https://api.pols.so/v1/sandboxes/string/computer/actions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"type\": \"click\",\n  \"x\": 0,\n  \"y\": 0,\n  \"to_x\": 0,\n  \"to_y\": 0,\n  \"button\": \"left\",\n  \"text\": \"string\",\n  \"keys\": \"ctrl+l\",\n  \"direction\": \"up\",\n  \"amount\": 3\n}"
});

import requests

response = requests.post(
    "https://api.pols.so/v1/sandboxes/string/computer/actions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"type\": \"click\",\n  \"x\": 0,\n  \"y\": 0,\n  \"to_x\": 0,\n  \"to_y\": 0,\n  \"button\": \"left\",\n  \"text\": \"string\",\n  \"keys\": \"ctrl+l\",\n  \"direction\": \"up\",\n  \"amount\": 3\n}",
)

Response

Done.

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}