# HTTP endpoints

Control the installed device server from your own HTTP client. This reference covers 54 registered method/path pairs. Each endpoint has parameters, a response description and a small curl example.

## Which address should I use?

| Address | Purpose |
| --- | --- |
| `http://DEVICE_LAN_IP:8080` | Direct access to your phone or iPad on a reachable local network |
| `http://127.0.0.1:18080` | Your computer, only after forwarding USB port 18080 to device port 8080 |
| `https://mcp.applesauceos.com/mcp` | MCP protocol with client authorization; it does not expose these paths directly |

No SSH is needed. Enable the device HTTP server in ApplesauceOS settings. Direct HTTP is unencrypted and does not use MCP pairing; use a trusted network or USB forwarding. Do not expose port 8080 publicly. If using MCP, call its tools instead of constructing device URLs.

## Make your first request

Replace the example IP with your device’s address:

```sh
DEVICE_URL='http://192.168.1.42:8080'
curl --fail-with-body "$DEVICE_URL/endpoints"
```

For USB, run `iproxy 18080:8080` on your computer and keep it running; use `DEVICE_URL='http://127.0.0.1:18080'` in another terminal. Device trust/pairing is required. The curl examples use a shell variable on your computer, not a JavaScript API.

## Save, run and inspect a script

```sh
curl --fail-with-body "$DEVICE_URL/files/write" \
  -H 'Content-Type: application/json' \
  -d '{"path":"Hello.cso/main.js","content":"console.log(\"Hello\");","overwrite":false}'

curl --fail-with-body "$DEVICE_URL/scripts/run" \
  -H 'Content-Type: application/json' \
  -d '{"path":"Hello.cso","repeat":1}'

# Replace RUN_UUID with the id returned above.
curl --fail-with-body "$DEVICE_URL/scripts/runs?id=RUN_UUID"
```

If the file already exists, read its current hash and follow the overwrite rules; do not blindly replace it. A submitted run is not a finished run. Poll its ID with a finite deadline and inspect both state and errors.

## Choose the right execution route

| Need | Start | Inspect | Stop |
| --- | --- | --- | --- |
| Normal saved script or .cso/.aso project | POST /scripts/run | GET /scripts/runs?id=... | POST /scripts/stop with id |
| Async JS body using return/await | POST /automation/run | GET /automation/runs?id=... | POST /automation/stop with runId |

Send JSON POST bodies with Content-Type: application/json. URL-encode query values. Response objects below describe fields, not a promise that every optional field is always present. Screenshots return PNG and some status/log routes return plain text.

## Browse by task

### Discovery

- [GET /](https://mcp.applesauceos.com/doc/http/get-index.md) — Open the device server’s HTML landing page.
- [GET /endpoints](https://mcp.applesauceos.com/doc/http/get-endpoints.md) — List the installed server’s exact methods and paths.
- [GET /automation](https://mcp.applesauceos.com/doc/http/get-automation.md) — Read the automation API capabilities and limits.

### Apps and device

- [GET /apps/list](https://mcp.applesauceos.com/doc/http/get-apps-list.md) — Find installed apps by name or bundle ID.
- [GET /appInfo](https://mcp.applesauceos.com/doc/http/get-appinfo.md) — Read metadata for one app.
- [POST /apps/open](https://mcp.applesauceos.com/doc/http/post-apps-open.md) — Bring an installed app to the foreground.
- [POST /device/button](https://mcp.applesauceos.com/doc/http/post-device-button.md) — Press and release one hardware button.
- [POST /device/touch](https://mcp.applesauceos.com/doc/http/post-device-touch.md) — Send a coordinate tap or swipe.
- [GET /device/screenshot](https://mcp.applesauceos.com/doc/http/get-device-screenshot.md) — Capture the full device screen, including overlays.
- [GET /deviceInfo](https://mcp.applesauceos.com/doc/http/get-deviceinfo.md) — Read device information.
- [GET /SN](https://mcp.applesauceos.com/doc/http/get-sn.md) — Read the device serial number.
- [GET /IP](https://mcp.applesauceos.com/doc/http/get-ip.md) — Read the local Wi-Fi IP address.
- [GET /tweakVersion](https://mcp.applesauceos.com/doc/http/get-tweakversion.md) — Read the installed ApplesauceOS version.
- [GET /temperature](https://mcp.applesauceos.com/doc/http/get-temperature.md) — Read device temperature when available.

### Script files

- [GET /files/list](https://mcp.applesauceos.com/doc/http/get-files-list.md) — List a Scripts directory or project.
- [GET /files/read](https://mcp.applesauceos.com/doc/http/get-files-read.md) — Read a page of a file and its current hash.
- [GET /files/download](https://mcp.applesauceos.com/doc/http/get-files-download.md) — Download a file as raw bytes.
- [POST /files/write](https://mcp.applesauceos.com/doc/http/post-files-write.md) — Create a file or replace a known version.
- [POST /files/mkdir](https://mcp.applesauceos.com/doc/http/post-files-mkdir.md) — Create a directory or project folder.
- [POST /files/move](https://mcp.applesauceos.com/doc/http/post-files-move.md) — Move or rename a file or directory.
- [POST /files/delete](https://mcp.applesauceos.com/doc/http/post-files-delete.md) — Delete one file or an empty directory.

### Saved scripts

- [POST /scripts/run](https://mcp.applesauceos.com/doc/http/post-scripts-run.md) — Run a saved script or project with ordinary launcher semantics.
- [GET /scripts/runs](https://mcp.applesauceos.com/doc/http/get-scripts-runs.md) — Inspect one saved-script run or recent journals.
- [POST /scripts/stop](https://mcp.applesauceos.com/doc/http/post-scripts-stop.md) — Request cancellation of one saved-script run.
- [GET /isBusy](https://mcp.applesauceos.com/doc/http/get-isbusy.md) — Read current script activity.
- [GET /runningScripts](https://mcp.applesauceos.com/doc/http/get-runningscripts.md) — List paths currently running.
- [GET /stopAll](https://mcp.applesauceos.com/doc/http/get-stopall.md) — Request cancellation of all non-daemon scripts.

### JavaScript jobs

- [POST /automation/run](https://mcp.applesauceos.com/doc/http/post-automation-run.md) — Execute an async JavaScript function body and retain its result.
- [GET /automation/runs](https://mcp.applesauceos.com/doc/http/get-automation-runs.md) — Read a retained JavaScript job and its structured result.
- [POST /automation/stop](https://mcp.applesauceos.com/doc/http/post-automation-stop.md) — Request cancellation of one JavaScript job.
- [POST /automation/delete](https://mcp.applesauceos.com/doc/http/post-automation-delete.md) — Remove a finished JavaScript job and its execution artifacts.

### UIHelper HTTP

- [GET /ui](https://mcp.applesauceos.com/doc/http/get-ui.md) — Read the UIHelper HTTP capabilities.
- [GET /ui/observe](https://mcp.applesauceos.com/doc/http/get-ui-observe.md) — Capture structured elements in the foreground app.
- [POST /ui/observe](https://mcp.applesauceos.com/doc/http/post-ui-observe.md) — Capture structured elements using JSON options.
- [POST /ui/query](https://mcp.applesauceos.com/doc/http/post-ui-query.md) — Check live selector matches and uniqueness.
- [GET /ui/element](https://mcp.applesauceos.com/doc/http/get-ui-element.md) — Read fresh attributes for an observed element.
- [POST /ui/action](https://mcp.applesauceos.com/doc/http/post-ui-action.md) — Perform one action on an observed element.
- [POST /ui/wait](https://mcp.applesauceos.com/doc/http/post-ui-wait.md) — Wait for a selector to appear or disappear.
- [GET /ui/screenshot](https://mcp.applesauceos.com/doc/http/get-ui-screenshot.md) — Retrieve the PNG belonging to an observation.
- [POST /ui/inspector](https://mcp.applesauceos.com/doc/http/post-ui-inspector.md) — Schedule opening or closing the device inspector.

### Diagnostics

- [GET /logs](https://mcp.applesauceos.com/doc/http/get-logs.md) — Read the shared script log.
- [GET /logs/clear](https://mcp.applesauceos.com/doc/http/get-logs-clear.md) — Clear the shared script log.
- [GET /lastError](https://mcp.applesauceos.com/doc/http/get-lasterror.md) — Read the last engine JavaScript error.
- [GET /diagnostics/crashes](https://mcp.applesauceos.com/doc/http/get-diagnostics-crashes.md) — List accessible device crash reports.
- [GET /diagnostics/crash](https://mcp.applesauceos.com/doc/http/get-diagnostics-crash.md) — Read a bounded page of a listed crash report.

### Settings

- [GET /settings](https://mcp.applesauceos.com/doc/http/get-settings.md) — Read the current preference snapshot.
- [POST /settings](https://mcp.applesauceos.com/doc/http/post-settings.md) — Apply a validated partial preference update.
- [GET /settings/logs](https://mcp.applesauceos.com/doc/http/get-settings-logs.md) — Read a bounded shared-log tail.
- [POST /settings/action](https://mcp.applesauceos.com/doc/http/post-settings-action.md) — Request a settings action.
- [GET /setDebugLog](https://mcp.applesauceos.com/doc/http/get-setdebuglog.md) — Read or change verbose diagnostic logging.
- [GET /setErrorAlert](https://mcp.applesauceos.com/doc/http/get-seterroralert.md) — Enable or disable script error popups.
- [GET /setScriptToasts](https://mcp.applesauceos.com/doc/http/get-setscripttoasts.md) — Read or change script start/finish notices.
- [GET /setSafeMode](https://mcp.applesauceos.com/doc/http/get-setsafemode.md) — Read or change safe-mode avoidance.
- [GET /setKeepAwake](https://mcp.applesauceos.com/doc/http/get-setkeepawake.md) — Read or change the keep-awake preference.

## Shared behavior

OPTIONS returns 204 for any path; it is not a capability check. Unknown method/path pairs return 404. Some GET routes change state (for example /stopAll, /logs/clear and settings toggles); do not prefetch or crawl those routes.

Read [HTTP workflows, field details and error handling](https://mcp.applesauceos.com/doc/http-guide.md) for file conflicts, observations, script arguments and limits. Discover the exact installed route set with GET /endpoints.