> ## 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.
# Scroll
> Move the pointer to a coordinate and scroll the wheel up or down there.
Moves the pointer to `x`, `y` and scrolls the wheel there. A Windows computer scrolls at the pointer's current position instead.
On Linux, always send `x` and `y`. The pointer is moved before every scroll, and
omitting either coordinate moves it to `0` on that axis. A request of
`{"direction": "down", "amount": 3}` warps the pointer to the top-left corner
and scrolls whatever happens to be under it. On Linux there is no way to scroll
at the pointer's current position through this endpoint.
A Windows computer scrolls at the pointer's current position and ignores
`?screen=`. Send it only `direction` and `amount`, both required: `direction`
must be `up` or `down` and `amount` from `1` to `50`. Any other field,
including `x` and `y`, or a value outside those rules returns `400`. A
successful response is `{"ok": true}`.
## 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 scroll 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. A Windows computer ignores this
parameter.
## Body parameters
X coordinate to move the pointer to before scrolling, in pixels from the left
edge. Nominally optional, but omitting it moves the pointer to `x = 0`. See
the warning above. A Windows computer refuses this field with `400`.
Y coordinate to move the pointer to before scrolling, in pixels from the top
edge. Nominally optional, but omitting it moves the pointer to `y = 0`. See
the warning above. A Windows computer refuses this field with `400`.
Scroll direction: `up` or `down`. Optional on Linux: omitting it scrolls down,
and so does any value other than the exact string `up`. Required on Windows.
Number of wheel clicks. Optional on Linux: omitting it, or sending `0`,
scrolls once, and a negative value moves the pointer, scrolls nothing, and
still returns `200`. Required on Windows, from `1` to `50`.
## Response
Always `true` on a `200`. A failed scroll is an error status.
Always `scroll`.
Carries `direction` and `amount` after defaults are applied. The coordinates
the pointer was moved to are not echoed back.
## Example
```bash cURL theme={null}
# Scroll down 3 clicks over (640, 400)
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/scroll \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"x": 640, "y": 400, "direction": "down", "amount": 3}'
# Scroll up 10 clicks over the same point
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/scroll \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"x": 640, "y": 400, "direction": "up", "amount": 10}'
```
```python Python theme={null}
import requests
requests.post(
f"https://www.orgo.ai/api/computers/{computer_id}/scroll",
headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
json={"x": 640, "y": 400, "direction": "down", "amount": 3}
)
```
```javascript JavaScript theme={null}
await fetch(`https://www.orgo.ai/api/computers/${computerId}/scroll`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ x: 640, y: 400, direction: 'down', amount: 3 })
});
```
### Response
```json theme={null}
{
"success": true,
"action": "scroll",
"details": { "direction": "down", "amount": 3 },
"error": null,
"error_type": null
}
```
## Errors
| Status | Meaning |
| - | - |
| `400` | The computer has no VM attached: `{"error": "Desktop instance not available"}`. Also returned by the computer agent when a body field has the wrong JSON type, such as `amount` sent as a string rather than a number. A Windows computer also returns it for a body outside its rules, as `{"error": "Request failed with status code 400"}` with `upstream_status: 400`. |
| `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` here, with `{"error": "Service temporarily unavailable. …"}`. 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 when `?screen=` names a screen this computer does not have. |
| `500` | The computer agent could not move the pointer or scroll, or the request body is not valid JSON. |
| `503` | The computer could not be reached: `{"error": "Could not reach the desktop. Try again in a moment.", "code": "ECONNREFUSED"}`. Safe to retry. A computer that never finished provisioning also returns `503`, with `{"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": "moving mouse for scroll: exit status 1",
"request_id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"upstream_status": 500
}
```
## OpenAPI
````yaml POST /computers/{id}/scroll
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}/scroll:
post:
tags:
- Computer Actions
summary: Scroll
description: Scrolls the mouse wheel up or down.
operationId: scroll
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/ScrollRequest'
example:
x: 640
'y': 400
direction: down
amount: 3
responses:
'200':
description: Scroll performed
content:
application/json:
schema:
$ref: '#/components/schemas/ActionResponse'
example:
success: true
action: scroll
details:
direction: down
amount: 3
error: null
error_type: null
'400':
description: >-
The computer has no VM attached, or the computer agent rejected a
body field of the wrong JSON type.
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
wrong-type:
summary: >-
The computer agent rejected a body field of the wrong JSON
type, such as `amount` sent as a string
value:
error: 'invalid JSON: …'
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 "2"
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 404
'500':
description: >-
The computer agent could not move the pointer or scroll, or the
request body is not valid JSON.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/UpstreamError'
- $ref: '#/components/schemas/InternalError'
examples:
agent-failed:
summary: Rejected by the computer agent
value:
error: 'moving mouse for scroll: exit status 1'
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:
ScrollRequest:
type: object
required:
- x
- 'y'
properties:
x:
type: integer
description: >-
X coordinate to move the pointer to before scrolling, in pixels from
the left edge. The pointer is moved before every scroll, so omitting
this warps it to `x = 0` and scrolls whatever is under that point.
Always send it.
'y':
type: integer
description: >-
Y coordinate to move the pointer to before scrolling, in pixels from
the top edge. The pointer is moved before every scroll, so omitting
this warps it to `y = 0` and scrolls whatever is under that point.
Always send it.
direction:
type: string
enum:
- up
- down
default: down
description: >-
Scroll direction. Optional. Omitting it scrolls down, and so does
any value other than the exact string `up`.
amount:
type: integer
default: 1
description: >-
Number of wheel clicks. Optional. Omitting it, or sending `0`,
scrolls once. A negative value moves the pointer, scrolls nothing,
and still returns `200`.
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.