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

# Keyboard Press

> Press a single key (printable char or special key name) with optional modifier hold.

## Overview

Dispatches a single keydown+keyup for a named key. Useful for submitting forms (Enter), dismissing dialogs (Escape), navigating selects (ArrowDown), or triggering shortcuts (Control+A).

## Path Parameters

<ParamField path="id" type="string" required={true}>
  Browser session ID (UUID).
</ParamField>

## Body

<ParamField body="key" type="string" required={true}>
  Either a single printable character (e.g. `a`, `1`, `!`) or one of the special keys:

  `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Space`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`, `PageUp`, `PageDown`, `F1`–`F12`.

  Unknown names return **400**.
</ParamField>

<ParamField body="selector" type="string">
  Optional CSS selector to click/focus before pressing.
</ParamField>

<ParamField body="timeout" type="integer" default="5000">
  How long to wait (ms) for the selector to become visible.
</ParamField>

<ParamField body="holdKeys" type="string[]">
  Modifier keys held for the duration of the press. Each value must be one of `Shift`, `Control`, `Alt`, `Meta`.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL (submit form) theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/.../keyboard/press" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "key": "Enter" }'
  ```

  ```bash cURL (select all) theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/.../keyboard/press" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "key": "a", "holdKeys": ["Control"] }'
  ```

  ```javascript JavaScript theme={null}
  await fetch(
    "https://api.scrapengine.io/api/v1/browser/sessions/.../keyboard/press",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ key: "Enter", holdKeys: ["Shift"] }),
    },
  );
  ```

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

  requests.post(
      "https://api.scrapengine.io/api/v1/browser/sessions/.../keyboard/press",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"key": "Enter", "holdKeys": ["Shift"]},
  )
  ```
</CodeGroup>

## Response

### Success Response (200)

<ResponseField name="success" type="boolean">
  True when the key was dispatched successfully.
</ResponseField>

<ResponseField name="key" type="string">
  The key that was pressed (echoed from the request).
</ResponseField>

**Example Response:**

```json theme={null}
{
  "success": true,
  "key": "Enter"
}
```

### Error Responses

| Status | Description                                                           |
| ------ | --------------------------------------------------------------------- |
| `400`  | Invalid body — missing key, unknown special-key name, bad modifier.   |
| `401`  | Unauthorized — invalid or missing API key.                            |
| `404`  | Session not found, or selector did not become visible before timeout. |
| `503`  | The browser session is temporarily unreachable.                       |

## Notes

* **No auto-submit.** `press: Enter` dispatches the key; any resulting form submission or navigation is the page's doing. Wait for page state separately if you need confirmation.
* **Chord syntax** is `key` + `holdKeys[]`, not a single string. Consistent with `/mouse/click`.
* **Holding keys across multiple presses** requires calling `press` for each key; modifier state is released after each call.

## Supported editor chords

The following `Ctrl`/`Meta` chords execute their editor command in addition to firing the keydown/keyup events, so you can select, copy, paste, and undo in text fields just like a user would:

| Chord                         | Action               |
| ----------------------------- | -------------------- |
| `Ctrl`/`Meta` + `A`           | Select all           |
| `Ctrl`/`Meta` + `C`           | Copy selection       |
| `Ctrl`/`Meta` + `X`           | Cut selection        |
| `Ctrl`/`Meta` + `V`           | Paste                |
| `Ctrl`/`Meta` + `Z`           | Undo                 |
| `Ctrl`/`Meta` + `Shift` + `Z` | Redo                 |
| `Ctrl`/`Meta` + `Y`           | Redo (Windows-style) |

Other `Ctrl`/`Meta` chords still dispatch the keydown event with the modifier set (page listeners see `ctrlKey: true`) but don't trigger browser-chrome accelerators like new-tab or close-tab.