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?

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:

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

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

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 / — Open the device server’s HTML landing page.
• GET /endpoints — List the installed server’s exact methods and paths.
• GET /automation — Read the automation API capabilities and limits.

Apps and device

• GET /apps/list — Find installed apps by name or bundle ID.
• GET /appInfo — Read metadata for one app.
• POST /apps/open — Bring an installed app to the foreground.
• POST /device/button — Press and release one hardware button.
• POST /device/touch — Send a coordinate tap or swipe.
• GET /device/screenshot — Capture the full device screen, including overlays.
• GET /deviceInfo — Read device information.
• GET /SN — Read the device serial number.
• GET /IP — Read the local Wi-Fi IP address.
• GET /tweakVersion — Read the installed ApplesauceOS version.
• GET /temperature — Read device temperature when available.

Script files

• GET /files/list — List a Scripts directory or project.
• GET /files/read — Read a page of a file and its current hash.
• GET /files/download — Download a file as raw bytes.
• POST /files/write — Create a file or replace a known version.
• POST /files/mkdir — Create a directory or project folder.
• POST /files/move — Move or rename a file or directory.
• POST /files/delete — Delete one file or an empty directory.

Saved scripts

• POST /scripts/run — Run a saved script or project with ordinary launcher semantics.
• GET /scripts/runs — Inspect one saved-script run or recent journals.
• POST /scripts/stop — Request cancellation of one saved-script run.
• GET /isBusy — Read current script activity.
• GET /runningScripts — List paths currently running.
• GET /stopAll — Request cancellation of all non-daemon scripts.

JavaScript jobs

• POST /automation/run — Execute an async JavaScript function body and retain its result.
• GET /automation/runs — Read a retained JavaScript job and its structured result.
• POST /automation/stop — Request cancellation of one JavaScript job.
• POST /automation/delete — Remove a finished JavaScript job and its execution artifacts.

UIHelper HTTP

• GET /ui — Read the UIHelper HTTP capabilities.
• GET /ui/observe — Capture structured elements in the foreground app.
• POST /ui/observe — Capture structured elements using JSON options.
• POST /ui/query — Check live selector matches and uniqueness.
• GET /ui/element — Read fresh attributes for an observed element.
• POST /ui/action — Perform one action on an observed element.
• POST /ui/wait — Wait for a selector to appear or disappear.
• GET /ui/screenshot — Retrieve the PNG belonging to an observation.
• POST /ui/inspector — Schedule opening or closing the device inspector.

Diagnostics

• GET /logs — Read the shared script log.
• GET /logs/clear — Clear the shared script log.
• GET /lastError — Read the last engine JavaScript error.
• GET /diagnostics/crashes — List accessible device crash reports.
• GET /diagnostics/crash — Read a bounded page of a listed crash report.

Settings

• GET /settings — Read the current preference snapshot.
• POST /settings — Apply a validated partial preference update.
• GET /settings/logs — Read a bounded shared-log tail.
• POST /settings/action — Request a settings action.
• GET /setDebugLog — Read or change verbose diagnostic logging.
• GET /setErrorAlert — Enable or disable script error popups.
• GET /setScriptToasts — Read or change script start/finish notices.
• GET /setSafeMode — Read or change safe-mode avoidance.
• GET /setKeepAwake — 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 for file conflicts, observations, script arguments and limits. Discover the exact installed route set with GET /endpoints.