> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudblast.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Computer Use

> Sees and drives the desktop of a running sandbox, one action per call. Only sandboxes created from a desktop image (`desktop: true`) have one.

Coordinates are screen pixels from the top left. Take a `screenshot` (or call `size`) first to learn the screen size.

| Action | Fields | Answer |
|---|---|---|
| `screenshot` | `format` (`jpeg` or `png`), `quality` | `width`, `height`, `format`, `image` (base64) |
| `size` | | `width`, `height` |
| `cursor` | | `x`, `y` |
| `move` | `x`, `y` (required) | |
| `click` | `x`, `y`, `button`, `count` | |
| `mouse_down`, `mouse_up` | `x`, `y`, `button` | |
| `drag` | `from`, `to` (required) | |
| `scroll` | `x`, `y`, `direction`, `amount` | |
| `type` | `text` (required) | |
| `key` | `keys` (required), `repeat` | |
| `open` | `target` (required), `args`, `wait` | |
| `windows` | | `windows` |
| `focus` | `window` (required) | |
| `read_screen` | `window`, `max_nodes` | the window's controls, numbered |
| `wait` | `seconds` | |

Without `x` and `y`, `click`, `mouse_down`, `mouse_up` and `scroll` act where the cursor is.

The actions that change the screen (`move`, `click`, `mouse_down`, `mouse_up`, `drag`, `scroll`, `type`, `key`, `open`, `focus`, `wait`) take `"screenshot": true` to return a picture taken just after, as `screenshot`, in the same answer.

Every action counts as activity and is in the sandbox's logs (without pictures, and with only the first 200 characters of typed text). An action that fails answers 422 with `data.ok: false` and the reason in `data.error`.

Rate limit: 600 a minute, counted apart from the rest of the API, see [Limits](/sandboxes#limits).



## OpenAPI

````yaml POST /sandboxes/{sandbox}/computer
openapi: 3.0.3
info:
  title: CloudBlast API
  description: >-
    The CloudBlast V2 API provides a modern RESTful interface for managing your
    cloud infrastructure programmatically. All responses follow a consistent `{
    "data": ... }` or `{ "error": ... }` format.
  version: 2.0.0
servers:
  - url: https://console.cloudblast.io/api/v2
    description: Production
security:
  - bearerAuth: []
paths:
  /sandboxes/{sandbox}/computer:
    post:
      tags:
        - Sandboxes
      summary: Computer use
      description: >-
        Sees and drives the desktop of a running sandbox, one action per call.
        Only sandboxes created from a desktop image (`desktop: true`) have one.


        Coordinates are screen pixels from the top left. Take a `screenshot` (or
        call `size`) first to learn the screen size.


        | Action | Fields | Answer |

        |---|---|---|

        | `screenshot` | `format` (`jpeg` or `png`), `quality` | `width`,
        `height`, `format`, `image` (base64) |

        | `size` | | `width`, `height` |

        | `cursor` | | `x`, `y` |

        | `move` | `x`, `y` (required) | |

        | `click` | `x`, `y`, `button`, `count` | |

        | `mouse_down`, `mouse_up` | `x`, `y`, `button` | |

        | `drag` | `from`, `to` (required) | |

        | `scroll` | `x`, `y`, `direction`, `amount` | |

        | `type` | `text` (required) | |

        | `key` | `keys` (required), `repeat` | |

        | `open` | `target` (required), `args`, `wait` | |

        | `windows` | | `windows` |

        | `focus` | `window` (required) | |

        | `read_screen` | `window`, `max_nodes` | the window's controls,
        numbered |

        | `wait` | `seconds` | |


        Without `x` and `y`, `click`, `mouse_down`, `mouse_up` and `scroll` act
        where the cursor is.


        The actions that change the screen (`move`, `click`, `mouse_down`,
        `mouse_up`, `drag`, `scroll`, `type`, `key`, `open`, `focus`, `wait`)
        take `"screenshot": true` to return a picture taken just after, as
        `screenshot`, in the same answer.


        Every action counts as activity and is in the sandbox's logs (without
        pictures, and with only the first 200 characters of typed text). An
        action that fails answers 422 with `data.ok: false` and the reason in
        `data.error`.


        Rate limit: 600 a minute, counted apart from the rest of the API, see
        [Limits](/sandboxes#limits).
      operationId: sandboxComputer
      parameters:
        - $ref: '#/components/parameters/SandboxIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxComputerAction'
            examples:
              screenshot:
                summary: Take a screenshot
                value:
                  action: screenshot
                  format: jpeg
                  quality: 70
              click:
                summary: Click, and see the screen after
                value:
                  action: click
                  x: 640
                  'y': 360
                  screenshot: true
              type:
                summary: Type text
                value:
                  action: type
                  text: Hello from my agent
              key:
                summary: Press keys in turn
                value:
                  action: key
                  keys:
                    - ctrl+a
                    - delete
              open:
                summary: Open a URL
                value:
                  action: open
                  target: https://example.com
                  wait: 3
              read_screen:
                summary: List the controls of the window in front
                value:
                  action: read_screen
                  max_nodes: 200
      responses:
        '200':
          description: The action was done
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SandboxComputerAnswer'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/SandboxNotFound'
        '409':
          $ref: '#/components/responses/SandboxNotRunning'
        '422':
          description: No desktop, a bad action or field, or the action failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxComputerError'
              examples:
                no_desktop:
                  summary: The sandbox has no desktop
                  value:
                    message: >-
                      This sandbox has no desktop. Start one from a desktop
                      image to use computer use.
                bad_field:
                  summary: A field is missing or out of range
                  value:
                    message: text is required, up to 20,000 characters.
                failed:
                  summary: The action failed
                  value:
                    message: The desktop did not answer within 60 seconds.
                    data:
                      ok: false
                      error: The desktop did not answer within 60 seconds.
components:
  parameters:
    SandboxIdentifier:
      name: sandbox
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: >-
        Sandbox UUID, as returned in the `uuid` field. Only the full UUID works
        here.
      example: 9b2f4c1e-7d3a-4e8b-a5c6-1f0e2d3c4b5a
  schemas:
    SandboxComputerAction:
      type: object
      required:
        - action
      description: >-
        One action. Each action reads only the fields it uses. Coordinates are
        screen pixels from the top left, 0 to 16384.
      properties:
        action:
          type: string
          enum:
            - screenshot
            - size
            - cursor
            - move
            - click
            - mouse_down
            - mouse_up
            - drag
            - scroll
            - type
            - key
            - open
            - windows
            - focus
            - read_screen
            - wait
          example: click
        x:
          type: integer
          minimum: 0
          maximum: 16384
          description: >-
            `move` (required), `click`, `mouse_down`, `mouse_up`, `scroll`:
            where to act. Give both `x` and `y`, or neither to act where the
            cursor is.
          example: 640
        'y':
          type: integer
          minimum: 0
          maximum: 16384
          description: See `x`.
          example: 360
        button:
          type: string
          enum:
            - left
            - middle
            - right
          default: left
          description: '`click`, `mouse_down`, `mouse_up`.'
        count:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: '`click`: 2 for a double click, 3 for a triple click.'
        from:
          type: object
          description: '`drag` (required): where to press the button.'
          required:
            - x
            - 'y'
          properties:
            x:
              type: integer
              minimum: 0
              maximum: 16384
              example: 200
            'y':
              type: integer
              minimum: 0
              maximum: 16384
              example: 150
        to:
          type: object
          description: '`drag` (required): where to let it go.'
          required:
            - x
            - 'y'
          properties:
            x:
              type: integer
              minimum: 0
              maximum: 16384
              example: 200
            'y':
              type: integer
              minimum: 0
              maximum: 16384
              example: 150
        direction:
          type: string
          enum:
            - up
            - down
            - left
            - right
          default: down
          description: '`scroll`.'
        amount:
          type: integer
          minimum: 1
          maximum: 30
          default: 3
          description: '`scroll`: how many notches.'
        text:
          type: string
          maxLength: 20000
          description: '`type` (required): the text to type, in any language.'
        keys:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 20
          description: >-
            `key` (required): one combination like `"ctrl+l"`, or a list pressed
            in turn like `["ctrl+a", "delete"]` (up to 20).
          example: ctrl+l
        repeat:
          type: integer
          minimum: 1
          maximum: 50
          default: 1
          description: '`key`: how many times to press them.'
        target:
          type: string
          maxLength: 2000
          description: '`open` (required): a URL, a file or an app.'
          example: https://example.com
        args:
          type: string
          maxLength: 2000
          description: '`open`: arguments for the app.'
        wait:
          type: integer
          minimum: 0
          maximum: 30
          description: '`open`: seconds to wait after opening it, before answering.'
        window:
          type: string
          maxLength: 200
          description: >-
            `focus` (required) and `read_screen`: a window `id` from `windows`,
            or part of its title. `read_screen` reads the window in front
            without it.
        max_nodes:
          type: integer
          minimum: 20
          maximum: 1500
          description: '`read_screen`: the most controls to list.'
        seconds:
          type: integer
          minimum: 0
          maximum: 30
          default: 1
          description: '`wait`: how long to wait.'
        format:
          type: string
          enum:
            - jpeg
            - png
          default: jpeg
          description: >-
            `screenshot`, and any action with `screenshot: true`: the format of
            the picture.
        quality:
          type: integer
          minimum: 10
          maximum: 100
          description: '`screenshot` in `jpeg`: the quality of the picture.'
        screenshot:
          type: boolean
          default: false
          description: >-
            On an action that changes the screen (`move`, `click`, `mouse_down`,
            `mouse_up`, `drag`, `scroll`, `type`, `key`, `open`, `focus`,
            `wait`): also take a screenshot just after, returned as
            `screenshot`.
    SandboxComputerAnswer:
      type: object
      description: >-
        Always `ok: true`. The other fields depend on the action, and can differ
        a little between Linux and Windows.
      additionalProperties: true
      properties:
        ok:
          type: boolean
          example: true
        width:
          type: integer
          description: '`screenshot`, `size`: screen width in pixels.'
          example: 1280
        height:
          type: integer
          description: '`screenshot`, `size`: screen height in pixels.'
          example: 800
        format:
          type: string
          enum:
            - jpeg
            - png
          description: '`screenshot`.'
        image:
          type: string
          format: byte
          description: '`screenshot`: the picture, base64-encoded.'
        x:
          type: integer
          description: '`cursor`, and the actions that move the pointer: where it is now.'
          example: 640
        'y':
          type: integer
          example: 360
        windows:
          type: array
          description: >-
            `windows` (and `focus`, and `open` on Linux): the open windows, each
            with an `id` to pass as `window`, and its `title`.
          items:
            type: object
            additionalProperties: true
            properties:
              id:
                type: string
                example: '0x03a00004'
              title:
                type: string
                example: Example Domain - Mozilla Firefox
              active:
                type: boolean
                example: true
        window:
          type: object
          additionalProperties: true
          description: '`read_screen`: the window that was read.'
        nodes:
          type: array
          description: >-
            `read_screen`: the controls of the window, numbered, each with its
            `role`, its `name` and the point to click (`x`, `y`).
          items:
            type: object
            additionalProperties: true
            properties:
              'n':
                type: integer
                example: 4
              role:
                type: string
                example: push button
              name:
                type: string
                example: More information...
              x:
                type: integer
                example: 512
              'y':
                type: integer
                example: 418
        truncated:
          type: boolean
          description: >-
            `read_screen`: true when the window has more controls than
            `max_nodes`.
        screenshot:
          $ref: '#/components/schemas/SandboxScreenshot'
    SandboxComputerError:
      type: object
      description: >-
        A computer use action that could not be done. `data` is only there when
        the action was sent to the desktop and failed there.
      properties:
        message:
          type: string
          example: The desktop did not answer within 60 seconds.
        data:
          type: object
          properties:
            ok:
              type: boolean
              example: false
            error:
              type: string
              description: Why the action failed.
              example: The desktop did not answer within 60 seconds.
      required:
        - message
    SandboxScreenshot:
      type: object
      properties:
        width:
          type: integer
          example: 1280
        height:
          type: integer
          example: 800
        format:
          type: string
          enum:
            - jpeg
            - png
          example: jpeg
        image:
          type: string
          format: byte
          description: The picture, base64-encoded.
          example: /9j/4AAQSkZJRgABAQAAAQABAAD...
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
          required:
            - code
            - message
    SandboxError:
      type: object
      description: >-
        How the sandbox endpoints answer an error: a `message`, not an error
        code. `errors` is only there when a request field failed validation.
      properties:
        message:
          type: string
          description: What went wrong, in plain words.
          example: Start the sandbox first.
        errors:
          type: object
          description: Messages per field, only when a field failed validation.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            image_id:
              - The image id field is required.
      required:
        - message
  responses:
    Unauthenticated:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHENTICATED
              message: >-
                Missing or invalid Authorization header. Use: Authorization:
                Bearer <token>
    SandboxNotFound:
      description: No sandbox with this UUID on your account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SandboxError'
          example:
            message: Sandbox not found.
    SandboxNotRunning:
      description: The sandbox is not running. Start it first.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SandboxError'
          example:
            message: Start the sandbox first.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token from your CloudBlast account settings. Pass as `Authorization:
        Bearer <token>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.