> ## 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.
# Drag mouse
> Press the left button at one coordinate, move, and release at another.
Presses the left mouse button at the start coordinate, moves to the end coordinate, and releases. The drag is one continuous motion; there is no way to set its speed, and on Linux the button is always the left one.
On a Windows computer the response is `{"ok": true}`, an optional `button` field (`left`, `right`, or `middle`) picks the button, and `?screen=` is ignored.
## 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 drag on. Optional. Omit it to
act on the screen the computer booted with. An unknown id returns `404` rather
than falling back to the default screen.
## Body parameters
All four coordinates are required, and each must be a non-negative integer. `0` is a valid coordinate. A missing, negative, or non-integer coordinate returns `400`.
X coordinate the drag starts at, in pixels from the left edge.
Y coordinate the drag starts at, in pixels from the top edge.
X coordinate the drag ends at, in pixels from the left edge.
Y coordinate the drag ends at, in pixels from the top edge.
## Response
Always `true` on a `200`. A failed drag is an error status.
Always `drag`.
Echo of the four coordinates that were used.
Always `null` on a `200`.
Always `null` on a `200`.
## Example
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/drag \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"start_x": 100,
"start_y": 100,
"end_x": 300,
"end_y": 200
}'
```
```python Python theme={null}
import requests
requests.post(
f"https://www.orgo.ai/api/computers/{computer_id}/drag",
headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
json={
"start_x": 100,
"start_y": 100,
"end_x": 300,
"end_y": 200
}
)
```
```javascript JavaScript theme={null}
await fetch(`https://www.orgo.ai/api/computers/${computerId}/drag`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
start_x: 100,
start_y: 100,
end_x: 300,
end_y: 200
})
});
```
### Response
```json theme={null}
{
"success": true,
"action": "drag",
"details": { "start_x": 100, "start_y": 100, "end_x": 300, "end_y": 200 },
"error": null,
"error_type": null
}
```
## Errors
| Status | Meaning |
| - | - |
| `400` | A coordinate is missing, negative, or not an integer, including a number sent as a string: `{"error": "start_x, start_y, end_x, and end_y are required non-negative integers"}`. Also returned when the computer has no VM attached: `{"error": "Desktop instance not available"}`. |
| `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."}`. |
| `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 \"2\"", "request_id": "…", "upstream_status": 404}`. |
| `500` | The computer agent could not perform the drag, or the request body is not valid JSON (with the parser's message in `error`). |
| `503` | The computer could not be reached: `{"error": "Could not reach the desktop. Try again in a moment.", "code": "ECONNREFUSED"}`. Safe to retry. Also returned when the computer never finished provisioning: `{"error": "Computer not ready"}`. |
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": "start_x, start_y, end_x, and end_y are required non-negative integers"
}
```
## OpenAPI
````yaml POST /computers/{id}/drag
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: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- 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}/drag:
post:
tags:
- Computer Actions
summary: Drag mouse
description: >-
Presses the left mouse button at the start coordinate, moves to the end
coordinate, and releases. On Linux the button is always the left one.
The speed cannot be set.
operationId: mouseDrag
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
- name: screen
in: query
required: false
description: >-
Which screen to act on. Omit for the boot screen. An unknown id
returns 404 rather than falling back.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DragRequest'
example:
start_x: 100
start_y: 100
end_x: 300
end_y: 200
responses:
'200':
description: Drag performed
content:
application/json:
schema:
$ref: '#/components/schemas/ActionResponse'
example:
success: true
action: drag
details:
start_x: 100
start_y: 100
end_x: 300
end_y: 200
error: null
error_type: null
'400':
description: >-
A coordinate is missing, negative, or not an integer (including a
number sent as a string), or the computer has no VM attached.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
coordinates:
summary: Missing or invalid coordinate
value:
error: >-
start_x, start_y, end_x, and end_y are required
non-negative integers
no-instance:
summary: The computer has no VM attached. Start it first.
value:
error: Desktop instance not available
'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 "2"
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 404
'500':
description: >-
The computer agent could not perform the drag, or the request body
is not valid JSON (with the parser's message in `error`).
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:
DragRequest:
type: object
required:
- start_x
- start_y
- end_x
- end_y
description: >-
On Linux the drag always uses the left button. There is no speed
setting. Each coordinate must be a non-negative integer: `0` is a valid
coordinate, and a missing, negative, or non-integer coordinate is
rejected with `400`.
properties:
start_x:
type: integer
minimum: 0
description: >-
X coordinate the drag starts at, in pixels from the left edge. A
non-negative integer.
start_y:
type: integer
minimum: 0
description: >-
Y coordinate the drag starts at, in pixels from the top edge. A
non-negative integer.
end_x:
type: integer
minimum: 0
description: >-
X coordinate the drag ends at, in pixels from the left edge. A
non-negative integer.
end_y:
type: integer
minimum: 0
description: >-
Y coordinate the drag ends at, in pixels from the top edge. A
non-negative integer.
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.