> ## 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.

# Click mouse

> Click at given screen coordinates, optionally with modifiers or a repeat count.

Moves the pointer to the given coordinates and clicks there.

<Note>
  On a Windows computer the request and response differ. The response is `{"ok": true}`. `double` uses the `button` you send rather than always the left one. An unrecognised `button`, a negative coordinate, or any `modifiers` or `repeat` field is refused with `400`, and the error body reads `Request failed with status code 400` rather than saying why. `?screen=` is ignored.
</Note>

## Path parameters

<ParamField path="id" type="string" required>
  Computer ID (UUID). An `instance_id` is not accepted here and fails with `500`.
</ParamField>

## Query parameters

<ParamField query="screen" type="string">
  Which [screen](/api-reference/screens/list) to click 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.
</ParamField>

## Body parameters

<ParamField body="x" type="integer" required>
  X coordinate, in pixels from the left edge. Omitting it is not rejected. The
  click lands at `0`.
</ParamField>

<ParamField body="y" type="integer" required>
  Y coordinate, in pixels from the top edge. Omitting it is not rejected. The
  click lands at `0`.
</ParamField>

<ParamField body="button" type="string" default="left">
  Which button to press: `left`, `right`, or `middle`. Any other value falls
  back to `left` without an error.
</ParamField>

<ParamField body="double" type="boolean" default="false">
  Double-click instead of single-clicking. `double` always uses the left button,
  so `button` has no effect when it is set. The response still echoes the
  `button` you sent.
</ParamField>

<ParamField body="modifiers" type="string[]">
  Keys held down for the duration of the click: `shift` to extend a selection,
  `ctrl` to add to one. Optional; omit for a plain click. One to four of `ctrl`
  (alias `control`), `alt` (alias `option`), `shift`, and `super` (aliases
  `cmd`, `meta`, `win`). An unrecognised name rejects the whole request rather
  than dropping one modifier and performing a different gesture. Cannot be
  combined with `double` or with `repeat` above 1.
</ParamField>

<ParamField body="repeat" type="integer" default="1">
  Number of clicks in rapid succession, so `3` is a triple-click. Optional;
  1 through 10. Values of 1 or below behave as a single click. The repeat is
  counted on the computer, so the gap between presses stays under the toolkit's
  multi-click threshold no matter how slow the network is. Cannot be combined
  with `modifiers`.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true` on a `200`. A refused or failed click is an error status.
</ResponseField>

<ResponseField name="action" type="string">
  `double_click` when `double` was set, `click` otherwise.
</ResponseField>

<ResponseField name="details" type="object">
  Echo of what was performed. Always carries `x`, `y`, and `button`. A plain
  click adds `double: false`; a repeat click adds `repeat`; a modified click
  adds `modifiers` with the names normalised (`option` comes back as `alt`).
</ResponseField>

<ResponseField name="error" type="null">
  Always `null` on a `200`.
</ResponseField>

<ResponseField name="error_type" type="null">
  Always `null` on a `200`.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  # Left click at (100, 200)
  curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"x": 100, "y": 200}'

  # Right click
  curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"x": 100, "y": 200, "button": "right"}'

  # Double click
  curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"x": 100, "y": 200, "double": true}'

  # Shift-click to extend a selection
  curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"x": 100, "y": 200, "modifiers": ["shift"]}'

  # Triple click to select a line
  curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"x": 100, "y": 200, "repeat": 3}'
  ```

  ```python Python theme={null}
  import requests

  url = f"https://www.orgo.ai/api/computers/{computer_id}/click"
  headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

  # Left click
  requests.post(url, headers=headers, json={"x": 100, "y": 200})

  # Right click
  requests.post(url, headers=headers, json={"x": 100, "y": 200, "button": "right"})

  # Double click
  requests.post(url, headers=headers, json={"x": 100, "y": 200, "double": True})

  # Ctrl-click to add to a selection
  requests.post(url, headers=headers, json={"x": 100, "y": 200, "modifiers": ["ctrl"]})

  # Triple click
  requests.post(url, headers=headers, json={"x": 100, "y": 200, "repeat": 3})
  ```

  ```javascript JavaScript theme={null}
  const url = `https://www.orgo.ai/api/computers/${computerId}/click`;
  const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  };

  // Left click
  await fetch(url, { method: 'POST', headers, body: JSON.stringify({ x: 100, y: 200 }) });

  // Right click
  await fetch(url, { method: 'POST', headers, body: JSON.stringify({ x: 100, y: 200, button: 'right' }) });

  // Ctrl-click to add to a selection
  await fetch(url, { method: 'POST', headers, body: JSON.stringify({ x: 100, y: 200, modifiers: ['ctrl'] }) });

  // Triple click
  await fetch(url, { method: 'POST', headers, body: JSON.stringify({ x: 100, y: 200, repeat: 3 }) });
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "success": true,
  "action": "click",
  "details": { "x": 100, "y": 200, "button": "left", "double": false },
  "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 for `modifiers` combined with `double` or `repeat` above 1, for `repeat` above 10, for an unrecognised modifier name, for more than four modifiers, and when a body field has the wrong JSON type, such as `x` sent as a string rather than a number. |
| `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 click, 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": "double cannot be combined with modifiers",
  "request_id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "upstream_status": 400
}
```


## OpenAPI

````yaml POST /computers/{id}/click
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}/click:
    post:
      tags:
        - Computer Actions
      summary: Click mouse
      description: Performs a mouse click at the specified coordinates.
      operationId: mouseClick
      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/ClickRequest'
            examples:
              left-click:
                summary: Left click
                value:
                  x: 100
                  'y': 200
              right-click:
                summary: Right click
                value:
                  x: 100
                  'y': 200
                  button: right
              double-click:
                summary: Double click
                value:
                  x: 100
                  'y': 200
                  double: true
      responses:
        '200':
          description: Click performed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
              example:
                success: true
                action: click
                details:
                  x: 100
                  'y': 200
                  button: left
                  double: false
                error: null
                error_type: null
        '400':
          description: >-
            The computer has no VM attached, or the computer agent rejected the
            body: `modifiers` combined with `double` or a `repeat` above 1,
            `repeat` above 10, an unrecognised modifier, more than four
            modifiers, or a 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
                bad-combination:
                  summary: Rejected by the computer agent
                  value:
                    error: double cannot be combined with modifiers
                    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 perform the click, 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:
    ClickRequest:
      type: object
      required:
        - x
        - 'y'
      properties:
        x:
          type: integer
          description: X coordinate
          minimum: 0
        'y':
          type: integer
          description: Y coordinate
          minimum: 0
        button:
          type: string
          enum:
            - left
            - right
            - middle
          default: left
          description: >-
            Which button to press. Any other value falls back to `left` without
            an error.
        double:
          type: boolean
          default: false
          description: >-
            Double-click instead of single-clicking. A double-click always uses
            the left button, so `button` has no effect when this is set. The
            response still echoes the `button` you sent.
        modifiers:
          type: array
          minItems: 1
          maxItems: 4
          items:
            type: string
            enum:
              - ctrl
              - control
              - alt
              - option
              - shift
              - super
              - cmd
              - meta
              - win
          description: >-
            Keys held down for the duration of the click. Use `shift` to extend
            a selection, `ctrl` to add to one. Optional: omit for a plain click.
            One to four of `ctrl` (alias `control`), `alt` (alias `option`),
            `shift`, and `super` (aliases `cmd`, `meta`, `win`). An unrecognised
            name rejects the whole request rather than dropping one modifier and
            performing a different gesture. Cannot be combined with `double` or
            with `repeat` above 1. The response echoes the names normalised, so
            `option` comes back as `alt`.
        repeat:
          type: integer
          default: 1
          minimum: 1
          maximum: 10
          description: >-
            Number of clicks in rapid succession, so `3` is a triple-click.
            Optional. Values of 1 or below behave as a single click, and a value
            above 10 is refused with `400`. The repeat is counted on the
            computer, so the gap between presses stays under the toolkit's
            multi-click threshold no matter how slow the network is. Cannot be
            combined with `modifiers`.
    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.