Kernel Browser Computer Controls API

openapi: 3.2.0
info:
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  title: Kernel Browser Computer Controls API
  version: 0.1.0
servers:
- description: API Server
  url: https://api.onkernel.com
security:
- bearerAuth: []
tags:
- description: Control mouse, keyboard, and screen on the browser instance.
  name: Browser Computer Controls
paths:
  /browsers/{id_or_name}/computer/batch:
    post:
      description: 'Send an array of computer actions to execute in order on the browser instance.

        Execution stops on the first error. This reduces network latency compared to

        sending individual action requests.'
      operationId: batchComputerAction
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchComputerActionRequest'
        required: true
      responses:
        '200':
          description: All actions executed successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Execute a batch of computer actions sequentially
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/click_mouse:
    post:
      operationId: clickMouse
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClickMouseRequest'
        required: true
      responses:
        '200':
          description: Mouse action performed
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Simulate a mouse click action on the browser instance
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/clipboard/read:
    post:
      operationId: readClipboard
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClipboardContent'
          description: Clipboard content read successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Read text from the clipboard on the browser instance
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/clipboard/write:
    post:
      operationId: writeClipboard
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteClipboardRequest'
        required: true
      responses:
        '200':
          description: Text written to clipboard successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Write text to the clipboard on the browser instance
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/cursor:
    post:
      operationId: setCursor
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCursorRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
          description: Cursor visibility set
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Set cursor visibility
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/drag_mouse:
    post:
      operationId: dragMouse
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DragMouseRequest'
        required: true
      responses:
        '200':
          description: Drag performed
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Drag the mouse along a path
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/get_mouse_position:
    post:
      operationId: getMousePosition
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MousePositionResponse'
          description: Current mouse position
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Get the current mouse cursor position on the browser instance
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/move_mouse:
    post:
      operationId: moveMouse
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveMouseRequest'
        required: true
      responses:
        '200':
          description: Mouse cursor moved
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Move the mouse cursor to the specified coordinates on the browser instance
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/press_key:
    post:
      operationId: pressKey
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PressKeyRequest'
        required: true
      responses:
        '200':
          description: Keys pressed successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Press one or more keys on the host computer
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/screenshot:
    post:
      operationId: takeScreenshot
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenshotRequest'
        required: false
      responses:
        '200':
          content:
            image/png:
              schema:
                format: binary
                type: string
          description: Screenshot image
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Capture a screenshot of the browser instance
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/scroll:
    post:
      operationId: scroll
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrollRequest'
        required: true
      responses:
        '200':
          description: Scroll performed
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Scroll the mouse wheel at a position on the host computer
      tags:
      - Browser Computer Controls
  /browsers/{id_or_name}/computer/type:
    post:
      operationId: typeText
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypeTextRequest'
        required: true
      responses:
        '200':
          description: Text typed successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Type text on the browser instance
      tags:
      - Browser Computer Controls
components:
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad Request – invalid input
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal Server Error
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource not found
    BrowserProxyError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceProxyError'
      description: Error returned by the browser or its proxy
  schemas:
    ClickMouseRequest:
      additionalProperties: false
      properties:
        button:
          description: Mouse button to interact with
          enum:
          - left
          - right
          - middle
          - back
          - forward
          type: string
        click_type:
          description: Type of click action
          enum:
          - down
          - up
          - click
          type: string
        hold_keys:
          description: Modifier keys to hold during the click
          items:
            type: string
          type: array
        num_clicks:
          default: 1
          description: Number of times to repeat the click
          type: integer
        'true':
          description: Y coordinate of the click position
          type: integer
        x:
          description: X coordinate of the click position
          type: integer
      required:
      - x
      - true
      type: object
    OkResponse:
      additionalProperties: false
      description: Generic OK response.
      properties:
        ok:
          default: true
          description: Indicates success.
          type: boolean
      required:
      - ok
      type: object
    DragMouseRequest:
      additionalProperties: false
      properties:
        button:
          description: Mouse button to drag with
          enum:
          - left
          - middle
          - right
          type: string
        delay:
          default: 0
          description: Delay in milliseconds between button down and starting to move along the path.
          minimum: 0
          type: integer
        duration_ms:
          description: Target total duration in milliseconds for the entire drag movement when smooth=true. Omit for automatic timing based on total path length.
          maximum: 10000
          minimum: 50
          type: integer
        hold_keys:
          description: Modifier keys to hold during the drag
          items:
            type: string
          type: array
        path:
          description: Ordered list of [x, y] coordinate pairs to move through while dragging. Must contain at least 2 points.
          items:
            items:
              type: integer
            maxItems: 2
            minItems: 2
            type: array
          minItems: 2
          type: array
        smooth:
          default: true
          description: Use human-like Bezier curves between path waypoints instead of linear interpolation. When true, steps_per_segment and step_delay_ms are ignored.
          type: boolean
        step_delay_ms:
          default: 50
          description: Delay in milliseconds between relative steps while dragging (not the initial delay).
          minimum: 0
          type: integer
        steps_per_segment:
          default: 10
          description: Number of relative move steps per segment in the path. Minimum 1.
          minimum: 1
          type: integer
      required:
      - path
      type: object
    WriteClipboardRequest:
      additionalProperties: false
      properties:
        text:
          description: Text to write to the system clipboard
          type: string
      required:
      - text
      type: object
    Error:
      properties:
        code:
          description: Application-specific error code (machine-readable)
          example: bad_request
          type: string
        details:
          description: Additional error details (for multiple errors)
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        inner_error:
          $ref: '#/components/schemas/ErrorDetail'
        message:
          description: Human-readable error description for debugging
          example: 'Missing required field: app_name'
          type: string
      required:
      - code
      - message
      type: object
    MoveMouseRequest:
      additionalProperties: false
      properties:
        duration_ms:
          description: Target total duration in milliseconds for the mouse movement when smooth=true. Omit for automatic timing based on distance.
          maximum: 5000
          minimum: 50
          type: integer
        hold_keys:
          description: Modifier keys to hold during the move
          items:
            type: string
          type: array
        smooth:
          default: true
          description: Use human-like Bezier curve path instead of instant mouse movement.
          type: boolean
        'true':
          description: Y coordinate to move the cursor to
          type: integer
        x:
          description: X coordinate to move the cursor to
          type: integer
      required:
      - x
      - true
      type: object
    InstanceProxyError:
      properties:
        code:
          $ref: '#/components/schemas/InstanceProxyErrorCode'
        message:
          description: Human-readable error description for debugging
          type: string
      required:
      - code
      - message
      type: object
    ScreenshotRegion:
      additionalProperties: false
      properties:
        height:
          description: Height of the region in pixels
          type: integer
        'true':
          description: Y coordinate of the region's top-left corner
          type: integer
        width:
          description: Width of the region in pixels
          type: integer
        x:
          description: X coordinate of the region's top-left corner
          type: integer
      required:
      - x
      - true
      - width
      - height
      type: object
    TypeTextRequest:
      additionalProperties: false
      properties:
        delay:
          default: 0
          description: Delay in milliseconds between keystrokes
          minimum: 0
          type: integer
        text:
          description: Text to type on the browser instance
          type: string
      required:
      - text
      type: object
    ClipboardContent:
      additionalProperties: false
      properties:
        text:
          description: Current clipboard text content
          type: string
      required:
      - text
      type: object
    InstanceProxyErrorCode:
      description: Canonical error code returned by browser instance API proxy routes
      enum:
      - invalid_request
      - unauthorized
      - forbidden
      - session_not_leased
      - not_found
      - conflict
      - session_gone
      - rate_limit_exceeded
      - internal_error
      - browser_unavailable
      type: string
    SleepAction:
      additionalProperties: false
      description: Pause execution for a specified duration.
      properties:
        duration_ms:
          description: Duration to sleep in milliseconds.
          maximum: 30000
          minimum: 0
          type: integer
      required:
      - duration_ms
      type: object
    ScreenshotRequest:
      additionalProperties: false
      properties:
        region:
          $ref: '#/components/schemas/ScreenshotRegion'
      type: object
    ScrollRequest:
      additionalProperties: false
      properties:
        delta_x:
          default: 0
          description: Horizontal scroll amount in xdotool "wheel units." Positive scrolls right, negative scrolls left.
          type: integer
        delta_y:
          default: 0
          description: Vertical scroll amount in xdotool "wheel units." Positive scrolls down, negative scrolls up.
          type: integer
        hold_keys:
          description: Modifier keys to hold during the scroll
          items:
            type: string
          type: array
        'true':
          description: Y coordinate at which to perform the scroll
          type: integer
        x:
          description: X coordinate at which to perform the scroll
          type: integer
      required:
      - x
      - true
      type: object
    BatchComputerActionRequest:
      additionalProperties: false
      description: A batch of computer actions to execute sequentially.
      properties:
        actions:
          description: Ordered list of actions to execute. Execution stops on the first error.
          items:
            $ref: '#/components/schemas/ComputerAction'
          maxItems: 100
          minItems: 1
          type: array
      required:
      - actions
      type: object
    ErrorDetail:
      properties:
        code:
          description: Lower-level error code providing more specific detail
          example: invalid_input
          type: string
        message:
          description: Further detail about the error
          example: Provided version string is not semver compliant
          type: string
      type: object
    ComputerAction:
      additionalProperties: false
      description: 'A single computer action to execute as part of a batch. The `type` field selects which

        action to perform, and the corresponding field contains the action parameters.

        Exactly one action field matching the type must be provided.

        '
      properties:
        click_mouse:
          $ref: '#/components/schemas/ClickMouseRequest'
        drag_mouse:
          $ref: '#/components/schemas/DragMouseRequest'
        move_mouse:
          $ref: '#/components/schemas/MoveMouseRequest'
        press_key:
          $ref: '#/components/schemas/PressKeyRequest'
        scroll:
          $ref: '#/components/schemas/ScrollRequest'
        set_cursor:
          $ref: '#/components/schemas/SetCursorRequest'
        sleep:
          $ref: '#/components/schemas/SleepAction'
        type:
          description: The type of action to perform.
          enum:
          - click_mouse
          - move_mouse
          - type_text
          - press_key
          - scroll
          - drag_mouse
          - set_cursor
          - sleep
          type: string
        type_text:
          $ref: '#/components/schemas/TypeTextRequest'
      required:
      - type
      type: object
    SetCursorRequest:
      additionalProperties: false
      properties:
        hidden:
          description: Whether the cursor should be hidden or visible
          type: boolean
      required:
      - hidden
      type: object
    MousePositionResponse:
      additionalProperties: false
      properties:
        'true':
          description: Y coordinate of the cursor
          type: integer
        x:
          description: X coordinate of the cursor
          type: integer
      required:
      - x
      - true
      type: object
    PressKeyRequest:
      additionalProperties: false
      properties:
        duration:
          default: 0
          description: Duration to hold the keys down in milliseconds. If omitted or 0, keys are tapped.
          minimum: 0
          type: integer
        hold_keys:
          description: Optional modifier keys to hold during the key press sequence.
          items:
            type: string
          type: array
        keys:
          description: 'List of key symbols to press. Each item should be a key symbol supported by xdotool

            (see X11 keysym definitions). Examples include "Return", "Shift", "Ctrl", "Alt", "F5".

            Items in this list could also be combinations, e.g. "Ctrl+t" or "Ctrl+Shift+Tab".

            Use X11 names for punctuation in combinations, such as "Ctrl+minus" or "Ctrl+plus".

            A literal hyphen is also accepted as an alias, so "Ctrl+-" is normalized to "Ctrl+minus".

            '
          items:
            type: string
          type: array
      required:
      - keys
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
x-service-info:
  categories:
  - browsers
  docs:
    apiReference: https://www.kernel.sh/docs
    homepage: https://www.kernel.sh
    llms: https://api.onkernel.com/llms.txt
x-provenance:
  method: harvested
  publisher: Kernel
  source: https://api.onkernel.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)