Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

List files on the iPhone over USB

/v1/leases/{lease}/filesGET
Lists a folder on the iPhone over USB (AFC). Without app the root is the media folder, /var/mobile/Media: DCIM (Camera Roll files), Downloads, Books, PublicStaging. With app the root is that app's Documents, only for apps with file sharing (fileSharing in GET apps). Works while the iPhone is locked, after its first unlock since boot. No Developer Mode.
Authorizationoptional
bearerAuth?Bearer <token>
Required on the tunnel. An API token of the account, from ghosthand tunnel url --new-token. The unix socket needs no token
Query Parameters
path *string
Absolute iPhone path, e.g. /DCIM/100APPLE/IMG_0002.PNG (no ..)
app?string
Bundle id of an app with file sharing; the path is then inside its container, e.g. /Documents/a.pdf
recursive?boolean
Also list everything in subfolders. Folders iOS does not allow are skipped.
Default: false
Response
200 · Entries of the folder; a file path gives that one file
entries *object[]
Show item properties
path *string
Absolute iPhone path
type *"file" | "directory"
size *integer
Bytes
modified *string (date-time)
Default · Error (RFC 9457 problem details). `code` is stable; switch on it, not on `title` or `detail`.
code *"invalid-request" | "unauthorized" | "not-found" | "device-not-found" | "no-device" | "multiple-devices" | "permission-denied" | "bluetooth-unavailable" | "bluetooth-disconnected" | "no-frame" | "device-locked" | "lock-failed" | "pairing-timeout" | "pointer-not-found" | "lock-state-unavailable" | "lockdown-unavailable" | "unlock-failed" | "mute-unconfirmed" | "text-not-found" | "wait-text-timeout" | "cancelled" | "lease-invalid" | "device-leased" | "recording-active" | "no-recording" | "recording-failed" | "daemon-busy" | "tunnel-offline" | "login-required" | "subscription-required" | "unsupported-in-mode" | "xctest-unavailable" | "task-failed" | "internal-error"
Stable error code. Switch on it; title and detail are for people.
title *string
Short summary of the code, the same for every error with this code
status *integer
HTTP status of the error. In stream mode the response status stays 200.
detail *string
What happened and what to do next. Agents should read it.
Request example
curl -X GET "https://ghosthand.dev/macs/studio/v1/leases/42/files?path=%3Cpath%3E" \
  -H "Authorization: Bearer <token>"
Response example
{
  "code": "device-leased",
  "title": "iPhone leased by another client",
  "status": 409,
  "detail": "Tommy's iPhone is in use by another lease:\n  ses_456 (book a table on OpenTable), acquired 2 min ago, last used 10 s ago (tap)\nDecide first: if that task is still active, give up or tell the user the iPhone is busy."
}