Skip to content

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/state

Parameters ​

None.

Responses ​

json
{
  "error": "",
  "data": {
    "ip": "192.168.1.100",
    "version": "1.8.0"
  }
}
FieldTypeDescription
ipstrThe device's current local IP address.
versionstrThe installed CatScript version.

Example ​

shell
curl http://192.168.1.100:5000/api/self/state

Get the Script List ​

http
GET /api/script

Parameters ​

None

Responses ​

json
{
  "error": "",
  "data": [
    "demo.py"
  ]
}

Example ​

shell
curl http://192.168.1.100:5000/api/script

Get the Content of a Script ​

http
GET /api/script/{name}

Parameters ​

NameDescription
nameThe 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.py

Update the Content of a Script ​

http
PUT /api/script/{name}

Parameters ​

NameDescription
nameThe name of the script
bodyThe 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.py

Delete a Script ​

http
DELETE /api/script/{name}

Parameters ​

NameDescription
nameThe name of the script

Responses ​

json
{
    "error": "",
    "data": {}
}

Example ​

shell
curl -X DELETE http://192.168.1.100:5000/api/script/demo.py

Run a Script ​

http
POST /api/script/{name}/run

Parameters ​

NameDescription
nameThe name of the script

Responses ​

json
{
    "error": "",
    "data": {}
}

Example ​

shell
curl -X POST http://192.168.1.100:5000/api/script/demo.py/run

Get the Running Script ​

http
GET /api/script/running

Parameters ​

None

Responses ​

json
{
  "error": "",
  "data": "demo.py"
}

Example ​

shell
curl http://192.168.1.100:5000/api/script/running

Stop a Script ​

http
POST /api/script/stop

Parameters ​

None

Responses ​

json
{
    "error": "",
    "data": {}
}

Example ​

shell
curl -X POST http://192.168.1.100:5000/api/script/stop

Capture the Screen ​

http
GET /api/screen/snapshot

Parameters ​

None.

Responses ​

json
{
  "error": "",
  "data": "<base64-encoded PNG>"
}

Example ​

shell
curl http://192.168.1.100:5000/api/screen/snapshot

Get the UI Element Tree ​

http
GET /api/ui/tree

Parameters ​

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 fieldTypeDescription
rolestrDisplay text of the element.
labelstrOptional accessibility label.
valuestrOptional accessibility value.
framelist[int][x, y, width, height] in screen pixels.
centerlist[int]Center point in screen pixels.
center_normlist[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 ​

errorDescription
no frontmost appNo app is in the foreground.
frontmost is SpringBoardThe home screen is in the foreground.
ui tree unavailableSpringBoard IPC failed.
AX runtime unavailableThe accessibility runtime is unavailable.

Example ​

shell
curl http://192.168.1.100:5000/api/ui/tree

Get Logs ​

http
GET /api/sys/log?id={id}

Parameters ​

NameDescription
idReturn 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"

Python automation for jailbroken iOS