> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Move mouse
> Move the pointer without pressing a button, to hover over menus, tooltips, and link previews.
Moves the pointer to the given coordinates without pressing a button. Use it to hover: to open a menu that appears under the pointer, a tooltip, a link preview, or a toolbar that shows only on hover. [Click](/api-reference/computers/click) and [drag](/api-reference/computers/drag) also move the pointer, but both press a button. To see what the hover opened, take a [screenshot](/api-reference/computers/screenshot) afterwards.
On a Windows computer the response is `{"ok": true}` and `?screen=` is ignored. A coordinate above 100000 is refused with `400`, and the error body reads `Request failed with status code 400` rather than saying why.
This endpoint moves the pointer. To move a computer to another workspace, use [Move computer](/api-reference/computers/move).
## Path parameters
Computer ID (UUID). An `instance_id` is not accepted here and fails with `500`.
## Query parameters
Which [screen](/api-reference/screens/list) to move the pointer on. Optional.
Omit it to act on the screen the computer booted with. Each screen has its own
pointer, so the pointer on every other screen stays where it is. An unknown id
returns `404` rather than falling back to the default screen.
## Body parameters
X coordinate, in pixels from the left edge. `0` is the left edge.
Y coordinate, in pixels from the top edge. `0` is the top edge.
Both coordinates are required and must be non-negative integers. A missing,
negative, fractional, or non-numeric value, or a body that is not JSON, returns
`400` before the computer is contacted. Any other field in the body is ignored.
## Response
Always `true` on a `200`. A failed move is an error status.
Always `mouse_move`.
Echo of the coordinates the pointer moved to: `x` and `y`.
Always `null` on a `200`.
Always `null` on a `200`.
## Example
```bash cURL theme={null}
# Hover at (640, 360)
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/mouse-move \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"x": 640, "y": 360}'
# Hover on a second screen
curl -X POST "https://www.orgo.ai/api/computers/$COMPUTER_ID/mouse-move?screen=screen-100" \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"x": 640, "y": 360}'
```
```python Python theme={null}
import os
import requests
response = requests.post(
f"https://www.orgo.ai/api/computers/{os.environ['COMPUTER_ID']}/mouse-move",
headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
json={"x": 640, "y": 360},
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch(
`https://www.orgo.ai/api/computers/${process.env.COMPUTER_ID}/mouse-move`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ORGO_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ x: 640, y: 360 }),
},
);
console.log(await response.json());
```
### Response
```json theme={null}
{
"success": true,
"action": "mouse_move",
"details": { "x": 640, "y": 360 },
"error": null,
"error_type": null
}
```
## Errors
| Status | Meaning |
| - | - |
| `400` | The computer has no VM attached: `{"error": "Desktop instance not available"}`. A body that is not JSON, or an `x` or `y` that is missing or is not a non-negative integer, returns `{"error": "x and y are required non-negative integers"}`. |
| `401` | Invalid API key: `{"error": "Invalid API key"}`. A request with no `Authorization` header returns `{"error": "Authentication required"}`. Access failures also return `401` on this endpoint, not `403`: `{"error": "You do not have access to this workspace."}` when you are neither the owner nor a member of the computer's workspace, `{"error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)."}` for a view-only member, and `{"error": "This API key cannot access this workspace (workspace_scope_mismatch)."}` for a workspace-scoped key used outside its workspace. A server-side fault while verifying the credential also returns `401`, with `{"error": "Service temporarily unavailable. The database is not accepting requests. Retry shortly."}`. Retry that one; the key is fine. |
| `402` | The computer was created as a free trial that is no longer active: `{"error": "Choose a plan to continue."}`. A computer paid for by its own subscription or dedicated purchase whose payment has lapsed returns `{"error": "Manage this computer’s payment in Account → Usage."}`. |
| `404` | No computer with this id: `{"error": "Desktop not found"}`. Also returned by the computer agent when `?screen=` names a screen this computer does not have, as in `{"error": "no screen \"screen-101\"", "request_id": "…", "upstream_status": 404}`. |
| `500` | The computer agent could not move the pointer, with its message in `error` and `upstream_status: 500`. Also returned when `id` is not a computer UUID. |
| `503` | The computer could not be reached: `{"error": "Could not reach the desktop. Try again in a moment.", "request_id": "…", "code": "ECONNREFUSED"}`. Safe to retry. Also returned when the computer never finished provisioning: `{"error": "Computer not ready", "request_id": "…"}`. |
Every failure raised after the request leaves the API layer also carries a
`request_id`. Quote it in support requests. When the computer agent itself
answered non-2xx, the body additionally carries `upstream_status`.
```json theme={null}
{
"error": "no screen \"screen-101\"",
"request_id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"upstream_status": 404
}
```
## OpenAPI
````yaml POST /computers/{id}/mouse-move
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
paths:
/computers/{id}/mouse-move:
post:
tags:
- Computer Actions
summary: Move mouse
description: >-
Moves the pointer to the given coordinates without pressing a button: a
hover. Use it for a menu, tooltip, or link preview that opens only under
a resting pointer. On Windows the response is `{"ok": true}`, `?screen=`
is ignored, and a coordinate above 100000 is refused with `400`.
operationId: mouseMove
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
- name: screen
in: query
required: false
description: >-
Which screen to move the pointer on. Omit for the boot screen. Each
screen has its own pointer. An unknown id returns 404 rather than
falling back.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MouseMoveRequest'
example:
x: 640
'y': 360
responses:
'200':
description: Pointer moved
content:
application/json:
schema:
$ref: '#/components/schemas/ActionResponse'
example:
success: true
action: mouse_move
details:
x: 640
'y': 360
error: null
error_type: null
'400':
description: >-
The computer has no VM attached, the body is not JSON, or `x` or `y`
is missing or not a non-negative integer. On Windows the computer
agent also refuses a coordinate above 100000.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/UpstreamError'
examples:
no-instance:
summary: The computer has no VM attached. Start it first.
value:
error: Desktop instance not available
bad-coordinates:
summary: x or y missing, negative, fractional, or not a number
value:
error: x and y are required non-negative integers
windows-bound:
summary: 'Windows: a coordinate above 100000'
value:
error: Request failed with status code 400
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 400
'401':
$ref: '#/components/responses/UnauthorizedWithAccess'
'402':
$ref: '#/components/responses/TrialInactive'
'404':
description: >-
No computer with this id, or `?screen=` names a screen this computer
does not have.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/UpstreamError'
examples:
no-computer:
summary: Unknown computer
value:
error: Desktop not found
no-screen:
summary: Unknown screen
value:
error: no screen "screen-101"
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 404
'500':
description: >-
The computer agent could not move the pointer, or `id` is not a
computer UUID.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/UpstreamError'
- $ref: '#/components/schemas/InternalError'
example:
error: …
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 500
'503':
description: >-
The computer could not be reached. It may be resuming, or its host
may be unhealthy. Retry in a moment. Also returned when the computer
never finished provisioning.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/UnreachableError'
- $ref: '#/components/schemas/InternalError'
examples:
unreachable:
summary: Unreachable
value:
error: Could not reach the desktop. Try again in a moment.
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
code: ECONNREFUSED
not-ready:
summary: The computer never finished provisioning
value:
error: Computer not ready
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
components:
schemas:
MouseMoveRequest:
type: object
description: >-
Where to move the pointer. Both coordinates are required non-negative
integers; anything else returns `400`. Any other field is ignored.
required:
- x
- 'y'
properties:
x:
type: integer
minimum: 0
description: X coordinate, in pixels from the left edge.
example: 640
'y':
type: integer
minimum: 0
description: Y coordinate, in pixels from the top edge.
example: 360
ActionResponse:
type: object
properties:
success:
type: boolean
description: Always `true` on a `200`. A failed action is an error status.
example: true
action:
type: string
description: >-
The action performed: `click`, `mouse_move`, `drag`, `type`,
`key_press`, `scroll`, or `wait`.
details:
type: object
additionalProperties: true
description: Echo of what was performed. Its fields depend on the action.
error:
type: 'null'
description: Always `null` on a `200`.
error_type:
type: 'null'
description: Always `null` on a `200`.
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
UpstreamError:
type: object
description: >-
A failure the computer itself returned, relayed with the computer's own
status.
required:
- error
- request_id
- upstream_status
properties:
error:
type: string
description: The message the computer returned.
request_id:
type: string
description: >-
Correlation id for this failure. The server logged the failure under
it, so quote it in a support report.
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status:
type: integer
description: >-
The status the computer returned. Mirrors the status of this
response.
example: 409
InternalError:
type: object
description: >-
An unexpected failure. Retrying is reasonable; if it persists, quote
`request_id`.
required:
- error
properties:
error:
type: string
request_id:
type: string
description: >-
Present on failures raised by a route that talks to a computer.
Absent on the others.
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
UnreachableError:
type: object
description: >-
The computer could not be reached. The diagnostic fields, present on the
command endpoints, say how far the request got.
required:
- error
- request_id
- code
properties:
error:
type: string
example: Could not reach the desktop. Try again in a moment.
request_id:
type: string
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
code:
type: string
description: >-
The socket-level error code, or `network_error` when none was
reported.
example: ECONNREFUSED
vm_status:
type:
- string
- 'null'
description: The computer's recorded status when the request failed.
desired_status:
type:
- string
- 'null'
description: >-
The status the computer was being driven towards, when one was
recorded.
host_reachable:
type:
- boolean
- 'null'
description: Whether the host running the computer answered.
desktop_api_reachable:
type:
- boolean
- 'null'
description: Whether the computer's own API answered.
hint:
type: string
description: What to do next, given the two reachability results.
responses:
UnauthorizedWithAccess:
description: >-
No usable credential, or an access check failed. This endpoint runs its
workspace access checks during authentication, so it answers a missing
membership, view-only access, or a key scoped to another workspace with
`401`, not `403`. A server-side fault while verifying the credential
also returns `401`, with a `Service temporarily unavailable` message.
Retry that one; the key is fine.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
no-access:
summary: Not the owner or a member of the workspace
value:
error: You do not have access to this workspace.
view-only:
summary: View-only member, and the request changes something
value:
error: >-
This workspace is view-only. Ask the owner for write access
(workspace_read_only).
scope-mismatch:
summary: The API key is scoped to another workspace
value:
error: >-
This API key cannot access this workspace
(workspace_scope_mismatch).
service-unavailable:
summary: Server-side fault while verifying the credential. Retry.
value:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
TrialInactive:
description: >-
The computer is a free trial computer whose trial is no longer active,
or it is paid for by its own subscription or dedicated purchase and that
payment has lapsed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
trial:
summary: Trial no longer active
value:
error: Choose a plan to continue.
payment:
summary: The computer's own payment has lapsed
value:
error: Manage this computer’s payment in Account → Usage.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.