181 lines
3.0 KiB
Markdown
181 lines
3.0 KiB
Markdown
# API Reference (v0.1)
|
|
|
|
Base URL: `http://127.0.0.1:8123`
|
|
|
|
If `CLICKTHROUGH_TOKEN` is set, include header:
|
|
|
|
```http
|
|
x-clickthrough-token: <token>
|
|
```
|
|
|
|
## `GET /health`
|
|
|
|
Returns status and runtime safety flags, including `exec` capability config.
|
|
|
|
## `GET /screen`
|
|
|
|
Query params:
|
|
|
|
- `with_grid` (bool, default `true`)
|
|
- `grid_rows` (int, default env or `12`)
|
|
- `grid_cols` (int, default env or `12`)
|
|
- `include_labels` (bool, default `true`)
|
|
- `image_format` (`png`|`jpeg`, default `png`)
|
|
- `jpeg_quality` (1-100, default `85`)
|
|
- `asImage` (bool, default `false`) — if `true`, return raw image bytes only (`image/png` or `image/jpeg`)
|
|
|
|
Default response includes base64 image and metadata (`meta.region`, optional `meta.grid`).
|
|
|
|
## `POST /zoom`
|
|
|
|
Body:
|
|
|
|
```json
|
|
{
|
|
"center_x": 1200,
|
|
"center_y": 700,
|
|
"width": 500,
|
|
"height": 350,
|
|
"with_grid": true,
|
|
"grid_rows": 20,
|
|
"grid_cols": 20,
|
|
"include_labels": true,
|
|
"image_format": "png",
|
|
"jpeg_quality": 90
|
|
}
|
|
```
|
|
|
|
Query params:
|
|
|
|
- `asImage` (bool, default `false`) — if `true`, return raw image bytes only (`image/png` or `image/jpeg`)
|
|
|
|
Default response returns cropped image + region metadata in global pixel coordinates.
|
|
|
|
## `POST /action`
|
|
|
|
Body: one action.
|
|
|
|
### Pointer target modes
|
|
|
|
#### Pixel target
|
|
|
|
```json
|
|
{
|
|
"mode": "pixel",
|
|
"x": 100,
|
|
"y": 200,
|
|
"dx": 0,
|
|
"dy": 0
|
|
}
|
|
```
|
|
|
|
#### Grid target
|
|
|
|
```json
|
|
{
|
|
"mode": "grid",
|
|
"region_x": 0,
|
|
"region_y": 0,
|
|
"region_width": 1920,
|
|
"region_height": 1080,
|
|
"rows": 12,
|
|
"cols": 12,
|
|
"row": 5,
|
|
"col": 9,
|
|
"dx": 0.0,
|
|
"dy": 0.0
|
|
}
|
|
```
|
|
|
|
`dx`/`dy` are normalized offsets in `[-1, 1]` inside the selected cell.
|
|
|
|
### Action examples
|
|
|
|
Click:
|
|
|
|
```json
|
|
{
|
|
"action": "click",
|
|
"target": {
|
|
"mode": "grid",
|
|
"region_x": 0,
|
|
"region_y": 0,
|
|
"region_width": 1920,
|
|
"region_height": 1080,
|
|
"rows": 12,
|
|
"cols": 12,
|
|
"row": 7,
|
|
"col": 3,
|
|
"dx": 0.2,
|
|
"dy": -0.1
|
|
},
|
|
"clicks": 1,
|
|
"button": "left"
|
|
}
|
|
```
|
|
|
|
Scroll:
|
|
|
|
```json
|
|
{
|
|
"action": "scroll",
|
|
"target": {"mode": "pixel", "x": 1300, "y": 740},
|
|
"scroll_amount": -500
|
|
}
|
|
```
|
|
|
|
Type text:
|
|
|
|
```json
|
|
{
|
|
"action": "type",
|
|
"text": "hello world",
|
|
"interval_ms": 20
|
|
}
|
|
```
|
|
|
|
Hotkey:
|
|
|
|
```json
|
|
{
|
|
"action": "hotkey",
|
|
"keys": ["ctrl", "l"]
|
|
}
|
|
```
|
|
|
|
## `POST /exec`
|
|
|
|
Execute a shell command on the host running Clickthrough.
|
|
|
|
```json
|
|
{
|
|
"command": "Get-Process | Select-Object -First 5",
|
|
"shell": "powershell",
|
|
"timeout_s": 20,
|
|
"cwd": "C:/Users/Paul",
|
|
"dry_run": false
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
- `shell` supports `powershell`, `bash`, `cmd`
|
|
- if `shell` is omitted, server uses `CLICKTHROUGH_EXEC_DEFAULT_SHELL`
|
|
- output is truncated based on `CLICKTHROUGH_EXEC_MAX_OUTPUT_CHARS`
|
|
- endpoint can be disabled with `CLICKTHROUGH_EXEC_ENABLED=false`
|
|
|
|
Response includes `stdout`, `stderr`, `exit_code`, timeout state, and execution metadata.
|
|
|
|
## `POST /batch`
|
|
|
|
Runs multiple `action` payloads sequentially.
|
|
|
|
```json
|
|
{
|
|
"actions": [
|
|
{"action": "move", "target": {"mode": "pixel", "x": 100, "y": 100}},
|
|
{"action": "click", "target": {"mode": "pixel", "x": 100, "y": 100}}
|
|
],
|
|
"stop_on_error": true
|
|
}
|
|
```
|