Computer Action

Execute a computer action

curl --request POST \
  --url https://api.example.com/computer-use \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "move_mouse",
  "coordinates": {
    "x": 123,
    "y": 123
  }
}
'

import requests

url = "https://api.example.com/computer-use"

payload = {
    "action": "move_mouse",
    "coordinates": {
        "x": 123,
        "y": 123
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({action: 'move_mouse', coordinates: {x: 123, y: 123}})
};

fetch('https://api.example.com/computer-use', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/computer-use",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => 'move_mouse',
    'coordinates' => [
        'x' => 123,
        'y' => 123
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/computer-use"

	payload := strings.NewReader("{\n  \"action\": \"move_mouse\",\n  \"coordinates\": {\n    \"x\": 123,\n    \"y\": 123\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/computer-use")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"move_mouse\",\n  \"coordinates\": {\n    \"x\": 123,\n    \"y\": 123\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/computer-use")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"move_mouse\",\n  \"coordinates\": {\n    \"x\": 123,\n    \"y\": 123\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "image": "<string>"
  }
}

{
  "status": "<string>",
  "error": "<string>"
}

POST

computer-use

Execute a computer action

curl --request POST \
  --url https://api.example.com/computer-use \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "move_mouse",
  "coordinates": {
    "x": 123,
    "y": 123
  }
}
'

import requests

url = "https://api.example.com/computer-use"

payload = {
    "action": "move_mouse",
    "coordinates": {
        "x": 123,
        "y": 123
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({action: 'move_mouse', coordinates: {x: 123, y: 123}})
};

fetch('https://api.example.com/computer-use', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/computer-use",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => 'move_mouse',
    'coordinates' => [
        'x' => 123,
        'y' => 123
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/computer-use"

	payload := strings.NewReader("{\n  \"action\": \"move_mouse\",\n  \"coordinates\": {\n    \"x\": 123,\n    \"y\": 123\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/computer-use")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"move_mouse\",\n  \"coordinates\": {\n    \"x\": 123,\n    \"y\": 123\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/computer-use")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"move_mouse\",\n  \"coordinates\": {\n    \"x\": 123,\n    \"y\": 123\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "image": "<string>"
  }
}

{
  "status": "<string>",
  "error": "<string>"
}

Execute actions like mouse movements, clicks, keyboard input, and screenshots in the Bytebot desktop environment.

Request

string

required

The type of computer action to perform. Must be one of: move_mouse, trace_mouse, click_mouse, press_mouse, drag_mouse, scroll, type_keys, press_keys, type_text, wait, screenshot, cursor_position.

Mouse Actions

move_mouse

object

required

The target coordinates to move to.

Show coordinates properties

number

required

X coordinate (horizontal position)

number

required

Y coordinate (vertical position)

Example Request

{
  "action": "move_mouse",
  "coordinates": {
    "x": 100,
    "y": 200
  }
}

trace_mouse

array

required

Array of coordinate objects for the mouse path.

Show path

object

Show properties

number

required

X coordinate

number

required

Y coordinate

array

Keys to hold while moving the mouse along the path.

Example Request

{
  "action": "trace_mouse",
  "path": [
    { "x": 100, "y": 100 },
    { "x": 150, "y": 150 },
    { "x": 200, "y": 200 }
  ],
  "holdKeys": ["shift"]
}

click_mouse

object

The coordinates to click (uses current cursor position if omitted).

Show coordinates properties

number

required

X coordinate (horizontal position)

number

required

Y coordinate (vertical position)

string

required

Mouse button to click. Must be one of: left, right, middle.

number

required

Number of clicks to perform.

array

Keys to hold while clicking (e.g., [‘ctrl’, ‘shift’])

Show holdKeys

string

Key name

Example Request

{
  "action": "click_mouse",
  "coordinates": {
    "x": 150,
    "y": 250
  },
  "button": "left",
  "clickCount": 2
}

press_mouse

object

The coordinates to press/release (uses current cursor position if omitted).

Show coordinates properties

number

required

X coordinate (horizontal position)

number

required

Y coordinate (vertical position)

string

required

Mouse button to press/release. Must be one of: left, right, middle.

string

required

Whether to press or release the button. Must be one of: up, down.

Example Request

{
  "action": "press_mouse",
  "coordinates": {
    "x": 150,
    "y": 250
  },
  "button": "left",
  "press": "down"
}

drag_mouse

array

required

Array of coordinate objects for the drag path.

Show path

object

Show properties

number

required

X coordinate

number

required

Y coordinate

string

required

Mouse button to use for dragging. Must be one of: left, right, middle.

array

Keys to hold while dragging.

Example Request

{
  "action": "drag_mouse",
  "path": [
    { "x": 100, "y": 100 },
    { "x": 200, "y": 200 }
  ],
  "button": "left"
}

scroll

object

The coordinates to scroll at (uses current cursor position if omitted).

Show coordinates properties

number

required

X coordinate

number

required

Y coordinate

string

required

Scroll direction. Must be one of: up, down, left, right.

number

required

Number of scroll steps to perform.

array

Keys to hold while scrolling.

Example Request

{
  "action": "scroll",
  "direction": "down",
  "scrollCount": 5
}

Keyboard Actions

type_keys

array

required

Array of keys to type in sequence.

Show keys

string

Key name

number

Delay between key presses in milliseconds.

Example Request

{
  "action": "type_keys",
  "keys": ["a", "b", "c", "enter"],
  "delay": 50
}

press_keys

array

required

Array of keys to press or release.

Show keys

string

Key name

string

required

Whether to press or release the keys. Must be one of: up, down.

Example Request

{
  "action": "press_keys",
  "keys": ["ctrl", "shift", "esc"],
  "press": "down"
}

type_text

string

required

The text string to type.

number

Delay between characters in milliseconds.

Example Request

{
  "action": "type_text",
  "text": "Hello, Bytebot!",
  "delay": 50
}

paste_text

string

required

The text to paste. Useful for special characters that aren’t on the standard keyboard.

Example Request

{
  "action": "paste_text",
  "text": "Special characters: ©®™€¥£ émojis 🎉"
}

System Actions

wait

number

required

Wait duration in milliseconds.

Example Request

{
  "action": "wait",
  "duration": 2000
}

screenshot

No parameters required.Example Request

{
  "action": "screenshot"
}

cursor_position

No parameters required.Example Request

{
  "action": "cursor_position"
}

application

string

required

The application to switch to. Available options: firefox, 1password, thunderbird, vscode, terminal, desktop, directory.

Example Request

{
  "action": "application",
  "application": "firefox"
}

Available Applications:

firefox - Mozilla Firefox web browser
1password - Password manager
thunderbird - Email client
vscode - Visual Studio Code editor
terminal - Terminal/console application
desktop - Switch to desktop
directory - File manager/directory browser

Response

Responses vary based on the action performed:

Default Response

Most actions return a simple success response:

{
  "success": true
}

Screenshot Response

Returns the screenshot as a base64 encoded string:

{
  "success": true,
  "data": {
    "image": "base64_encoded_image_data"
  }
}

Cursor Position Response

Returns the current cursor position:

{
  "success": true,
  "data": {
    "x": 123,
    "y": 456
  }
}

Error Response

{
  "success": false,
  "error": "Error message"
}

Code Examples

curl -X POST http://localhost:9990/computer-use \
  -H "Content-Type: application/json" \
  -d '{"action": "move_mouse", "coordinates": {"x": 100, "y": 200}}'

import requests

def control_computer(action, **params):
    url = "http://localhost:9990/computer-use"
    data = {"action": action, **params}
    response = requests.post(url, json=data)
    return response.json()

# Move the mouse
result = control_computer("move_mouse", coordinates={"x": 100, "y": 100})
print(result)

const axios = require("axios");

async function controlComputer(action, params = {}) {
  const url = "http://localhost:9990/computer-use";
  const data = { action, ...params };
  const response = await axios.post(url, data);
  return response.data;
}

// Move mouse example
controlComputer("move_mouse", { coordinates: { x: 100, y: 100 } })
  .then((result) => console.log(result))
  .catch((error) => console.error("Error:", error));

Body

application/json

action

enum<string>

required

Available options:

move_mouse

coordinates

object

required

Show child attributes

Response

Successful response

success

boolean

required

data

object

Option 1
Option 2

Show child attributes

Getting Started

User Guides

Deployment

Core Concepts

Request

Mouse Actions

Keyboard Actions

System Actions

Response

Default Response

Screenshot Response

Cursor Position Response

Error Response

Code Examples

Body

Response

​Request

​Mouse Actions

​Keyboard Actions

​System Actions

​Response

​Default Response

​Screenshot Response

​Cursor Position Response

​Error Response

​Code Examples

Body

Response

Request

Mouse Actions

Keyboard Actions

System Actions

Response

Default Response

Screenshot Response

Cursor Position Response

Error Response

Code Examples