154 lines
2.2 KiB
Markdown
154 lines
2.2 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.
|
|
|
|
## `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`)
|
|
|
|
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
|
|
}
|
|
```
|
|
|
|
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 /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
|
|
}
|
|
```
|