Appearance
API Reference
CatScript exposes an HTTP API for remote control and script management. Every response uses the same envelope:
json
{
"error": "",
"data": {}
}An empty error means the request succeeded.
TIP
The base URL is http://<device-ip>:5000/api.
WARNING
When Allow LAN Access is disabled in Settings, requests from other devices are rejected. Only 127.0.0.1 and ::1 can access the web interface or API.
Get the Server State
http
GET /api/self/stateParameters
None.
Responses
json
{
"error": "",
"data": {
"ip": "192.168.1.100",
"version": "1.8.0"
}
}| Field | Type | Description |
|---|---|---|
| ip | str | The device's current local IP address. |
| version | str | The installed CatScript version. |
Example
shell
curl http://192.168.1.100:5000/api/self/stateGet the Script List
http
GET /api/scriptParameters
None
Responses
json
{
"error": "",
"data": [
"demo.py"
]
}Example
shell
curl http://192.168.1.100:5000/api/scriptGet the Content of a Script
http
GET /api/script/{name}Parameters
| Name | Description |
|---|---|
| name | The name of the script |
Responses
json
{
"error": "",
"data": "The content of the script"
}Example
shell
curl http://192.168.1.100:5000/api/script/demo.pyUpdate the Content of a Script
http
PUT /api/script/{name}Parameters
| Name | Description |
|---|---|
| name | The name of the script |
| body | The new content of the script |
Responses
json
{
"error": "",
"data": {}
}Example
shell
curl -X PUT --data-binary @local.py http://192.168.1.100:5000/api/script/demo.pyDelete a Script
http
DELETE /api/script/{name}Parameters
| Name | Description |
|---|---|
| name | The name of the script |
Responses
json
{
"error": "",
"data": {}
}Example
shell
curl -X DELETE http://192.168.1.100:5000/api/script/demo.pyRun a Script
http
POST /api/script/{name}/runParameters
| Name | Description |
|---|---|
| name | The name of the script |
Responses
json
{
"error": "",
"data": {}
}Example
shell
curl -X POST http://192.168.1.100:5000/api/script/demo.py/runGet the Running Script
http
GET /api/script/runningParameters
None
Responses
json
{
"error": "",
"data": "demo.py"
}Example
shell
curl http://192.168.1.100:5000/api/script/runningStop a Script
http
POST /api/script/stopParameters
None
Responses
json
{
"error": "",
"data": {}
}Example
shell
curl -X POST http://192.168.1.100:5000/api/script/stopCapture the Screen
http
GET /api/screen/snapshotParameters
None.
Responses
json
{
"error": "",
"data": "<base64-encoded PNG>"
}Example
shell
curl http://192.168.1.100:5000/api/screen/snapshotGet the UI Element Tree
http
GET /api/ui/treeParameters
None.
Responses
json
{
"error": "",
"data": {
"app": "com.apple.Preferences",
"pid": 12345,
"screen": {
"w": 750,
"h": 1334
},
"elements": [
{
"role": "Wi-Fi",
"value": "My Network",
"frame": [32, 1200, 686, 90],
"center": [375, 1246],
"center_norm": [0.5, 0.934]
}
]
}
}| Element field | Type | Description |
|---|---|---|
| role | str | Display text of the element. |
| label | str | Optional accessibility label. |
| value | str | Optional accessibility value. |
| frame | list[int] | [x, y, width, height] in screen pixels. |
| center | list[int] | Center point in screen pixels. |
| center_norm | list[float] | Center point normalized to 0.0–1.0. |
Notes
- The tree is sampled from the frontmost app only.
- The result is a flat list sampled by hit-testing, not a full accessibility hierarchy.
- Elements smaller than 44×44 pt, covered elements, and partially offscreen elements may be missing.
- The endpoint is unavailable when SpringBoard is in the foreground.
- A request may take a few seconds on complex screens.
- The response may contain personal information visible on the current screen.
Errors
error | Description |
|---|---|
no frontmost app | No app is in the foreground. |
frontmost is SpringBoard | The home screen is in the foreground. |
ui tree unavailable | SpringBoard IPC failed. |
AX runtime unavailable | The accessibility runtime is unavailable. |
Example
shell
curl http://192.168.1.100:5000/api/ui/treeGet Logs
http
GET /api/sys/log?id={id}Parameters
| Name | Description |
|---|---|
| id | Return log entries with an ID greater than this value. Use 0 to get all logs. |
Responses
json
{
"error": "",
"data": [
[0, "2026-11-20 23:00:00", "Log message"]
]
}Example
shell
curl "http://192.168.1.100:5000/api/sys/log?id=0"