HTTP API

Returns an array of every device MobAI sees. Devices on another MobAI computer that someone else is using are left out, since every action on them would be refused.

Response

[{
  "id": "00008130-001A2C3E0A1B401E",
  "name": "iPhone 15 Pro",
  "platform": "ios",
  "model": "iPhone16,1",
  "osVersion": "18.2",
  "bridgeRunning": true,
  "virtual": false,
  "transport": "USB",
  "connectionState": "ready",
  "controlUrl": "http://127.0.0.1:8787/device/00008130-001A2C3E0A1B401E?server=http%3A%2F%2F127.0.0.1%3A8686",
  "screenWidth": 393,
  "screenHeight": 852
}]

Note: inUse and the fields after it are left out when false or empty.

Returns one device as the same object GET /devices lists. An unknown id answers 404.

{"error": "device not found"}

Claims the named device, or any free one. Every field is optional. An empty body claims any free device. From this computer, a claim without device only picks devices attached to this computer, never remote or cloud ones.

{"device": "emulator-5554", "holder": "ci-runner-3"}

Response

{
  "deviceId": "emulator-5554",
  "leaseToken": "q3J8Zk1mW0xYb2VnT3pQdkR4c1N5aGJm",
  "expiresAt": "2026-11-05T10:40:00Z",
  "device": {"id": "emulator-5554", "name": "Pixel 8", "platform": "android", ...}
}

Note: Every failed claim answers 409 so a caller can poll until a device frees up.

Frees the device held by the token. 400 without a token, 404 when no claim matches it.

{"leaseToken": "q3J8Zk1mW0xYb2VnT3pQdkR4c1N5aGJm"}

Response

{"status": "released"}

Note: A device the user gave to an App Builder agent session stays claimed until the user frees it. Releasing it answers {"status": "kept", "message": "..."} and renews the claim.

Extends a claim by its full lifetime without touching the device. Calls that send X-Lease-Token already do this, so you only need it while the device sits idle. 404 means the claim expired or never existed: claim again.

{"leaseToken": "q3J8Zk1mW0xYb2VnT3pQdkR4c1N5aGJm"}

Response

{"expiresAt": "2026-11-05T11:10:00Z"}

Captures the screen and saves it to a file on this computer, then returns the path. Add ?format=base64 to get the image in the response instead.

Response

// Default
{"path": "/tmp/mobai/screenshots/emulator-5554-1762337400.png", "format": "png"}

// ?format=base64
{"data": "iVBORw0KGgoAAAANSUhEUgAA...", "format": "png"}

// ?low_quality=true, when the image had to be shrunk
{"path": "/tmp/mobai/screenshots/emulator-5554-1762337400.jpeg", "format": "jpeg", "scale": 2, "tip": "Screenshot downscaled 2x. ..."}

Note: A low_quality image matches action coordinates unless scale is present. Then multiply any x and y you read from the image by scale before tapping. UI tree coordinates never need this.

Returns the elements on screen as text, one line each: [index] Type "text" #accessibilityId [state] (x,y widthxheight). Child elements are indented. The index is what tap and the other actions take as index, and the bounds are in action coordinates.

Response

{
  "tree": "[0] Application \"Settings\" (0,0 393x852)\n  [6] Switch \"Airplane Mode\" [off] (16,180 361x44)\n  [7] Button \"Wi-Fi\" #wifi-cell (16,224 361x44)\n",
  "activity": ""
}

With verbose=true, trimmed

"elements": [{
  "index": 6, "parentIndex": 2, "depth": 2,
  "type": "android.widget.Switch", "text": "Airplane mode", "value": "0",
  "clickable": true, "enabled": true,
  "x": 32, "y": 448, "width": 1016, "height": 132
}]

Each element can also carry contentDesc, accessibilityId, editable, scrollable, focused, selected, hittable, possiblyOccluded (something may cover it) and clipped (how many points or pixels a scrolling parent cuts off each edge: top, bottom, left, right). Flags that are false are left out.

Note: A tree over 30,000 characters keeps only buttons, switches and text fields and starts with a warning line. On iOS the text read from the screen is added after it. activity is usually empty: use GET /devices/{id}/state for the app in front.

Reads the text on screen and names common icons. Useful for system sheets that show no elements in the UI tree. iOS only (iPhones and simulators). Android devices answer 400.

Response

{
  "elements": [{"text": "Sign In", "confidence": 0.98, "x": 150, "y": 400, "width": 100, "height": 30, "centerX": 200, "centerY": 415}],
  "icons": [{"x": 345, "y": 58, "width": 24, "height": 24, "centerX": 357, "centerY": 70, "distance": 0.11,
             "labels": [{"label": "share", "symbol": "square.and.arrow.up", "distance": 0.11}]}],
  "imageSize": {"width": 1179, "height": 2556},
  "screenSize": {"width": 393, "height": 852},
  "scale": 3.0
}

Note: Tap centerX, centerY. They are in screen points like every other action. Each icon lists candidate names, nearest first. icons is left out when none were found.

Taps an element by its UI tree index, a point, or a point given as a percentage of the screen. Send one of the three. When several are sent, index wins, then x/y.

{"index": 7}
{"x": 195, "y": 422}
{"xPercent": 50, "yPercent": 90}

Response

{"success": true, "data": {"x": 196, "y": 246}}  // the point tapped

Double taps. Same fields and response as /tap.

Presses and holds. Same fields and response as /tap, plus duration: how long to hold in milliseconds (default: 500).

{"index": 7, "duration": 1200}

Taps with two fingers at once, side by side around the point. Same fields and response as /tap. Works on iOS and Android.

{"x": 196, "y": 426, "scale": 2.0}

Response

{"success": true, "data": {"x": 196, "y": 426, "scale": 2}}

Swipes from one point to another. duration is in milliseconds (default: 300). All four coordinates at 0 answers 400, which usually means misspelled field names.

{"fromX": 200, "fromY": 600, "toX": 200, "toY": 200, "duration": 300}

Drags from one point to another, slower than a swipe. Use it to move icons, reorder rows or pull a slider.

{"fromX": 100, "fromY": 200, "toX": 300, "toY": 400, "pressDuration": 800}

Drags one finger through a list of points, for drawing, signatures or pattern locks. At least 2 points. The first point is where the finger goes down, and its duration_ms is an optional hold before moving. On every later point duration_ms is how long the move to it takes, and must be above 0.

{"points": [
  {"x": 100, "y": 400, "duration_ms": 0},
  {"x": 150, "y": 300, "duration_ms": 150},
  {"x": 300, "y": 500, "duration_ms": 300}
]}

Scrolls until an element whose text contains targetText is on screen, inside the list when you name one.

{"targetText": "Privacy", "listIndex": 3}

Response

{
  "found": true,
  "element": {"index": 41, "type": "Cell", "text": "Privacy & Security", "x": 16, "y": 610, "width": 361, "height": 44},
  "uiTree": {"tree": "...", "elements": [...], "activity": ""}
}

// not found
{"found": false}

Scrolls through a list and returns each element it saw once. It stops at the end of the list or at maxElements, and gives up after 5 minutes.

Response

{
  "elements": [
    {"index": 12, "type": "StaticText", "text": "Airplane Mode", "x": 60, "y": 190, "width": 120, "height": 22}
  ],
  "count": 1
}

Types into the field that has focus. Tap the field first.

{"text": "Hello World"}

Empties the text field that has focus. No body. On iOS, a screen with no focused field answers 500.

Presses a key by name. A name the platform does not have answers 400.

{"key": "back"}

Hides the on-screen keyboard. No body. On Android this presses Back, so with no keyboard open it goes back a screen.

Goes to the home screen. No body.

Opens a web address or a deep link on the device. url is required.

{"url": "https://example.com"}
{"url": "myapp://orders/42"}

Says which app is in front, whether the keyboard is up, and on Android which element has focus.

Response

// iOS
{"activity": "Settings (com.apple.Preferences)", "packageName": "com.apple.Preferences", "keyboardShown": false}

// Android
{
  "activity": "",
  "keyboardShown": true,
  "focusedElement": {
    "index": 7, "type": "android.widget.EditText", "text": "Search",
    "bounds": {"x": 42, "y": 180, "width": 996, "height": 126},
    "clickable": true, "editable": true, "focused": true, "enabled": true
  }
}

Returns the plain text on the device clipboard.

{"text": "123456"}

Puts plain text on the device clipboard, ready to paste.

{"text": "[email protected]"}

Makes the device report this location to apps. Both lat and lon at 0 answers 400.

{"lat": 40.7128, "lon": -74.0060}

Note: Android phones need Android 12 or later and answer 400 otherwise. Emulators, iPhones and iOS simulators work on any version.

Returns the device to its real location. An Android emulator has no real location, so it moves to 0, 0. Same Android 12 limit as above.

Sets the hinge of a foldable iOS simulator and returns once the device has settled on its new screen. Screenshots, taps, the UI tree and the screen size then follow the screen in use. Foldable iOS simulators only, so Mac only. Any other device answers 400.

{"state": "open"}
{"angle": 90}

Lists the apps on the device. iOS apps that declare Siri activities, intents or shortcut actions also carry a siri object.

[
  {"bundleId": "com.apple.Preferences", "name": "Settings", "version": "1.0"},
  {"bundleId": "com.example.notes", "name": "Notes", "version": "2.4.1",
   "siri": {"activities": ["com.example.notes.new"], "intents": ["INCreateNoteIntent"], "shortcutActions": ["compose"]}}
]

Installs an .apk on Android, an .ipa on an iPhone, or an .app on a simulator. Pass a path on this computer as JSON, or upload the file as multipart/form-data in a field named app (up to 4 GB) when it lives on another machine.

{"path": "/Users/me/builds/app-debug.apk"}

// iPhone, signed with an Apple ID first
{"path": "/Users/me/builds/App.ipa", "resign": true, "appleId": "[email protected]"}

// Upload the file instead of passing a path
curl -F "[email protected]" http://127.0.0.1:8686/api/v1/devices/{id}/install-app

Response

// With resign: where the signed IPA and signing files went. Pass the
// three paths back next time to skip Apple.
{
  "success": true,
  "data": {
    "bundleId": "com.example.app",
    "signedIpa": "/Users/me/builds/App-signed.ipa",
    "teamId": "A1B2C3D4E5",
    "profilePath": "/Users/me/builds/...",
    "certPath": "/Users/me/builds/...",
    "keyPath": "/Users/me/builds/..."
  }
}

Without resign the answer is {"success": true, "data": {}}, or {"success": true} for an upload. Signing can ask for a two-factor code in the MobAI window and may take up to 10 minutes.

Cloud devices: the build goes to the farm's app storage instead of a device, and the answer is {"success": true, "installed": false, "appRef": "...", "message": "..."}. Start the bridge with {"app": "<appRef>"} to run a session with it. resign is refused there.

Opens an app by bundle id (iOS) or package name (Android).

{"bundleId": "com.example.app", "arguments": ["-resetState"], "environment": {"API_URL": "http://localhost:3000"}}

Note: On Android and simulators this route starts the bridge, like the action routes. An iPhone launches without it, and so do a launch with withDebugger and a simulator launch with noWait.

Force-quits a running app. bundleId is required.

{"bundleId": "com.example.app"}

Removes the app and its data from the device. A failure answers 500 with the device's reason.

Installs the bridge if needed and starts it. Answers at once when it is already running. An iPhone's first start can take a few minutes while its bridge is built or signed (5 minute limit). The body is optional and only used by cloud farm devices.

Response

{"success": true}

Note: On the Free plan a second device answers 402 device_limit_reached while another one's bridge is running.

Stops the bridge and ends any claim on the device, so the next caller can take it. Answers {"success": true}.

Gives a task in plain words to MobAI's agent, which works the device until it is done. The call returns when the agent finishes. It uses the provider, model and keys from the app's AI settings.

{"task": "Open Settings and turn on Airplane Mode", "agentType": "toolagent"}

Response

{"success": true, "result": "Airplane Mode is on."}

Note: 400 without task. 412 when the key the agent needs is not set in the app. Agents the app offers that are not in this table cannot run through this route, so pass agentType when the app's pick is one of them. success is the agent's own verdict: a task it could not finish still answers 200 with "success": false.

Runs the steps in order and returns a result for each. For a device on another MobAI computer the whole script runs there, and files it makes come back to this computer.

{
  "version": "0.2",
  "steps": [
    {"action": "open_app", "bundle_id": "com.android.settings"},
    {"action": "tap", "predicate": {"text_contains": "Network"}}
  ],
  "on_fail": {"strategy": "abort"}
}

Response

{
  "success": true,
  "step_results": [
    {"success": true, "step_index": 0, "action": "open_app", "started_at_ms": 1762337400120, "duration_ms": 812},
    {"success": true, "step_index": 1, "action": "tap", "started_at_ms": 1762337400932, "duration_ms": 240,
     "result": {"matched_element": {"index": 12, "type": "android.widget.TextView", "text": "Network & internet",
                 "bounds": {"x": 189, "y": 640, "width": 402, "height": 59}}}}
  ],
  "total_time_ms": 1052,
  "metadata": {"interactive_elements": {"buttons": 4, "switches": 0, "text_fields": 1}, ...}
}

A failed step still answers 200, with "success": false on the script and an error on the step (code, message, and when useful candidates and hint). Screenshots from observe steps and debug blocks are saved as files, and the result holds their paths with "screenshot_saved": true. started_at_ms is a Unix time in milliseconds.

Note: A body that is not valid JSON answers 400, and a script that cannot run at all answers 500. Both look like {"code": "EXECUTION_ERROR", "message": "..."}.

Lists the open pages and selects the first one that answers. That page has isActive: true. On Android, id is the page's place in the list, so call this again after tabs open or close.

Response

[{
  "id": 1,
  "title": "Example Domain",
  "url": "https://example.com/",
  "appId": "412",
  "isActive": true
}]

Makes another page the target of the web routes. Answers 400 when the page is not open on the device.

{"pageId": 1}
// Response
{"success": true}

Returns the selected page's HTML as it is now, scripts' changes included.

{"dom": "<html><head>...</head><body>...</body></html>"}

Loads a URL in the selected page. url is required.

{"url": "https://example.com"}
// Response
{"success": true}

Clicks the first element that matches a CSS selector. Fails when nothing matches.

{"selector": "button.submit"}

Focuses the first input or textarea that matches, sets its value and fires input and change events, so React and Vue forms see the new value. It replaces the value in one go and does not press keys.

{"selector": "input#email", "text": "[email protected]"}

Runs JavaScript in the selected page and returns the value of the script as an expression. A top-level return is a syntax error, so write document.title, or wrap longer code in a function you call right away. A script error comes back with wasThrown: true and the message in error.

{"script": "Array.from(document.links).map(a => a.href)"}

// Response
{"value": ["https://www.iana.org/domains/example"], "wasThrown": false}

// Script error
{"value": null, "wasThrown": true, "error": "ReferenceError: Can't find variable: foo"}

Closes the connection to the browser. The next GET /web/pages opens a new one. Answers {"success": true}.

Forwards a port on this computer to a port on the device. The forward stays until you stop it.

{"devicePort": 8080}
// Response
{"hostPort": 49152, "devicePort": 8080, "id": "android-emulator-5554-49152-8080-1762337702000000000"}

Same body as POST /forward. Answers at once in plain text, then keeps the request open. The forward ends when you close the connection, so a script cannot leave one behind.

# Request
curl -N -X POST http://127.0.0.1:8686/api/v1/devices/{id}/forward/hold -d '{"devicePort": 8080}'

# Response (plain text, then the request stays open)
forwarded 8080 -> 49152

Stops the forward with the id that POST /forward returned. Answers {"success": true}.

Streams the device log as Server-Sent Events: one JSON entry per data: line, with no event names. The stream stays open until you close it. On Android it starts with the lines already in the device's log buffer, then follows new ones. iPhones and simulators send only new lines. A device that cannot stream logs closes the stream with no events.

Stream

# Android
data: {"timestamp":"2026-11-05T10:15:02Z","process":"AndroidRuntime","pid":"5678","level":"E","tag":"AndroidRuntime","message":"FATAL EXCEPTION: main"}

# iPhone
data: {"timestamp":"2026-11-05T10:15:02","device":"iPhone","process":"SpringBoard","pid":"58","level":"Notice","message":"..."}

Fields: timestamp, process and message are always there. device is iPhone only and tag Android only. raw holds a line that could not be read into fields. Simulator entries carry the timestamp, the process and the rest of the line in message.

Returns the device's app crash reports, newest first, at most 10. Works on simulators, iPhones and Android devices. A simulator's reports are read from this computer and only that simulator's apps count. An iPhone's reports are copied to this computer first, so the first call can take a while. Android covers crashes, native crashes and ANRs, for installed apps and apps that came with the phone. Farm devices answer 501.

Response

{
  "reports": [{
    "time": "2026-11-05T10:12:44Z",
    "app": "com.example.shelf",
    "process": "Shelf",
    "kind": "crash",
    "exception": "EXC_BREAKPOINT (SIGTRAP)",
    "reason": "the app crashed: Shelf/BookList.swift:42: Fatal error: Index out of range",
    "frames": ["BookList.row(at:) (Shelf)", "closure #1 in BookList.body.getter (Shelf)"],
    "path": "/Users/you/Library/Logs/DiagnosticReports/Shelf-2026-11-05-101244.ips"
  }]
}

kind is crash, or on Android also native_crash or anr. reason says why in one sentence and names kills from outside the app, such as iOS ending an app whose main thread was blocked too long. frames is the top of the crashed thread, up to 15. path is the whole report, a file on this computer. A bad app or since answers 400.

Starts sampling in the background. Samples are also written to a file on this computer, named in the summary's data_file.

{
  "types": ["system_cpu", "system_memory", "fps"],
  "bundleId": "com.example.shelf",
  "label": "checkout"
}
// Response
{"sessionId": "5f0c2a8e-3b1d-4c7a-9e57-2d8f6b1a0c94", "deviceId": "emulator-5554", "startedAt": "2026-11-05T10:15:02Z"}

Stops the session. The body is optional. By default the answer is the summary, the same shape as GET /metrics/summary. With "format": "detailed" it is only the session ID and sample count. Answers 404 when the device has no session.

{"format": "detailed"}
// Response
{"sessionId": "5f0c2a8e-3b1d-4c7a-9e57-2d8f6b1a0c94", "samples": 183}

Returns the summary of the running session without stopping it. Each part is there only when its metric was sampled. app needs bundleId. Statuses are healthy, warning or critical.

Response (trimmed)

{
  "metrics_summary": {
    "session": {
      "label": "checkout",
      "duration_seconds": 61.4,
      "sample_count": 183,
      "session_id": "5f0c2a8e-3b1d-4c7a-9e57-2d8f6b1a0c94",
      "data_file": ".../mobai/data/metrics/5f0c2a8e-3b1d-4c7a-9e57-2d8f6b1a0c94.jsonl",
      "logs_available": false
    },
    "overall_health": "warning",
    "health_score": 74,
    "system_cpu": {"avg": 41.2, "max": 88.0, "min": 12.5, "p95": 79.3, "status": "warning"},
    "fps": {"avg": 52.1, "min": 18.0, "max": 60.0, "p5": 24.0, "jank_percent": 6.5, "status": "warning"},
    "app": {"bundle_id": "com.example.shelf", "cpu_avg": 22.4, "cpu_max": 61.0, "memory_avg_bytes": 182452224, "memory_max_bytes": 201326592, "memory_growth_mb": 14.2, "sample_count": 61, "status": "healthy"},
    "anomalies": {"fps_drops": [{"start_s": 12.0, "end_s": 15.0, "min_fps": 18.0, "avg_fps": 22.5, "samples": 3}]},
    "recommendations": ["FPS dropped to 18 at +12.0s (3 occurrences) - investigate screen transitions"]
  }
}

Returns the samples the running session holds, one array per type. Types with no samples are left out. 404 without a session.

{
  "cpu": [{"timestamp": "2026-11-05T10:15:03Z", "totalLoad": 23.5, "cpuCount": 6, "enabledCpu": 6}],
  "memory": [{"timestamp": "2026-11-05T10:15:03Z", "usedBytes": 3951820800, "freeBytes": 2490368000, "totalBytes": 6442188800, "usagePercent": 61.3, "physFootprint": 0}],
  "processes": [{"timestamp": "2026-11-05T10:15:03Z", "pid": 5678, "name": "com.example.shelf", "cpuUsage": 12.0, "memoryBytes": 182452224}]
}

Server-Sent Events for the running session. Sends the buffered samples first, then new ones as they come. When the session stops it sends an end event and closes. 404 without a session.

data: {"type":"system_cpu","timestamp":"2026-11-05T10:15:03Z","data":{"timestamp":"2026-11-05T10:15:03Z","totalLoad":23.5,"cpuCount":6,"enabledCpu":6}}

event: end
data: session stopped

Takes one reading without starting a session. ?types= is a comma-separated list of metric types, default system_cpu,system_memory. Unknown names are skipped.

{
  "timestamp": "2026-11-05T10:15:03Z",
  "cpu": {"timestamp": "2026-11-05T10:15:03Z", "totalLoad": 18.2, "cpuCount": 6, "enabledCpu": 6},
  "memory": {"timestamp": "2026-11-05T10:15:03Z", "usedBytes": 3951820800, "freeBytes": 2490368000, "totalBytes": 6442188800, "usagePercent": 61.3, "physFootprint": 0}
}

Launches the app, restarting it if it runs, and writes everything it prints to a file on this computer until it exits. Answers once the app prints its first line, or 504 after 30 seconds of silence. Works on iPhones, simulators and Android. On Android it follows the app's log lines and clears the device's log buffer first. Stop it with POST /kill-app.

{"bundleId": "com.example.shelf", "environment": {"API_URL": "http://localhost:3000"}}
// Response
{"logPath": "/var/folders/xy/T/mobai/debug/com.example.shelf.log"}
// Each line of the file
2026-11-05T10:15:02.123456Z [stdout] Loaded 12 books

A WebSocket that launches the app and sends its output as it comes. iOS only: iPhones and simulators. bundleId is required. To pass environment variables or arguments, send one JSON message within half a second of connecting. Each message from MobAI is JSON with type stdout, exit, crash or error.

// Connect
ws://127.0.0.1:8686/api/v1/devices/{id}/debug?bundleId=com.example.shelf

// Optional first message from you
{"environment": {"API_URL": "http://localhost:3000"}, "arguments": ["-reset"]}

// Messages from MobAI
{"type": "stdout", "data": "Loaded 12 books"}
{"type": "exit", "data": "0", "message": "Process exited normally"}

Launches the app fresh with the debugger attached. Answers 409 when the device already has a session.

{"bundleId": "com.example.shelf", "breakpoints": ["BookList.swift:42"]}

// Response: the session
{
  "sessionId": "...",
  "deviceId": "6C1F2A0B-...",
  "pid": 48211,
  "bundleId": "com.example.shelf",
  "state": "running",
  "breakpoints": [{"id": 1, "spec": "BookList.swift:42", "verified": true, "source": {"path": "BookList.swift", "name": "BookList.swift"}, "line": 42}]
}

Attaches to an app that is already running, by process ID. Takes breakpoints and stopOnEntry like attach. Answers the session.

{"pid": 48211, "breakpoints": ["BookList.swift:42"]}

Returns the session, the same shape attach answers. Poll it to see when a breakpoint pauses the app. 404 without a session.

Works while the app runs. verified: false means it was not found: no debug info at that line, or a symbol name that does not match.

{"spec": "BookList.swift:42"}
// Response
{"id": 2, "spec": "BookList.swift:42", "verified": true}

bpId is the id from add. Answers {"success": true}.

direction is in, over, out or continue. The first three wait for the next stop and answer with the stack and the top frame's variables. Set includeStack or includeVars to false to leave either out. Both default to true. continue answers the session at once: poll GET /debug-session for the next pause.

{"direction": "over"}

// Response for in, over, out
{
  "state": "paused",
  "breakpoints": [...],
  "stack": [{"id": 1, "name": "BookList.reload()", "source": {"path": "/Users/you/code/shelf/BookList.swift", "name": "BookList.swift"}, "line": 43, "column": 9}],
  "frame0Locals": [{"name": "Locals", "variables": [{"name": "count", "value": "12", "type": "Int"}]}]
}

Frames of the thread that stopped, or of ?threadId=.

{"frames": [{"id": 1, "name": "BookList.reload()", "source": {"path": "/Users/you/code/shelf/BookList.swift", "name": "BookList.swift"}, "line": 42, "column": 9}]}

frameId is a frame id from the stack.

{"scopes": [{"name": "Locals", "variables": [{"name": "count", "value": "12", "type": "Int"}]}]}

Takes what Xcode's debugger console takes: p, po, frame variable. frameId is optional and defaults to the top frame of the thread that stopped.

{"expression": "po self.books.count"}
// Response
{"result": "12"}

Ends the session. The app keeps running unless you send kill: true. The body is optional.

{"kill": true}

Stops the device's session if there is one, then starts a new one. Answers 200 once the app runs with hot reload on, or 422 with the failed session and its log. A Flutter build can take minutes. React Native needs a Debug build, and an iPhone also needs the same Wi-Fi as this computer and Local Network access for the app.

{"framework": "flutter", "dir": "/Users/you/code/shelf"}

// Response: the session
{
  "deviceId": "6C1F2A0B-...",
  "framework": "flutter",
  "dir": "/Users/you/code/shelf",
  "state": "running",
  "vmServiceUrl": "http://127.0.0.1:50123/AbCdEf=/",
  "log": ["Syncing files to device iPhone 16 Pro...", "Flutter run key commands."]
}

Returns the session with the last lines of its log. ?lines= sets how many, default 80. The session keeps the last 400. 404 without a session.

Flutter: a hot reload, or a hot restart with restart: true. React Native: reloads the app, and restart is ignored. The body is optional. Answers the session with result. A failed reload answers 422 with error, for example code that does not compile, with the compiler errors in log. 404 without a session.

{"restart": false}
// Response (trimmed)
{"state": "running", "result": "Reloaded 1 of 812 libraries in 412ms.", "log": [...]}

Ends the session and the app it launched. Answers {"stopped": true}, or 404 without a session.

CI devices only: devices a mobai-ci run shares with the app. Builds the folder as it is now on the CI machine with its mobai.json build command, else the job's own build, then installs and launches the app. Ends any hot reload session on the device. Answers when the build ends: 200 when done, 422 with the end of the build log when it failed. Other devices answer 400.

{"dir": "/Users/you/code/shelf"}
// Response (trimmed)
{"state": "done", "appPath": "build/ios/iphonesimulator/Runner.app", "bundleId": "com.example.shelf", "launched": true, "log": ["..."]}

CI devices: POST /dev, POST /dev/reload and POST /rebuild send the folder as it is now, committed or not, to the CI machine, and the session runs there. The folder must be a clone of the repository the CI job runs.

Every available iOS simulator, booted or not. runtime is the runtime identifier, the same value POST /simulators takes.

[{
  "udid": "6C1F2A0B-5D3E-4F7A-9B21-8E0C4D6A1F33",
  "name": "iPhone 16 Pro",
  "state": "Booted",
  "runtime": "...iOS-18-2",   // trimmed
  "osVersion": "18.2"
}]

Creates a simulator and answers 201. It stays shut down until you boot it. Answers 422 when no installed iOS runtime supports the device type.

{"deviceType": "iPhone 16 Pro", "name": "Test iPhone"}
// Response
{"udid": "0B7E1C44-2A9D-4E61-8F05-3C1D7A9B2E10", "runtime": "...iOS-18-2"}

Boots the simulator without opening the Simulator app and answers 204 once it is ready, within 2 minutes. A simulator that is already booted is fine.

Shuts the simulator down. Answers 204.

Makes a copy with the same apps and data, for running tests in parallel. name is required. A booted source is shut down for the copy and booted again after. Answers 201, within 5 minutes.

{"name": "iPhone 16 Pro (2)"}
// Response
{"udid": "9D2B6F10-7C3A-4B85-A1E4-5F0D2C8B7A66"}

Erases all content and settings. A booted simulator is shut down first and stays shut down. Answers 204.

Deletes the simulator, shutting it down first if it runs. Answers 204.

Says how many of the background services MobAI can turn off are off. The simulator must be booted, else 422. persistent says whether the runtime keeps them off across reboots.

{"managedDisabled": 180, "managedTotal": 180, "booted": true, "persistent": true, "slim": true}

Slimming turns off background services a simulator does not need for testing, such as Siri, Spotlight, photo analysis and iCloud, so it uses far less memory and more simulators fit on one Mac. The simulator restarts to apply the change and is booted when the call answers. Needs an iOS 18.5 or later runtime, else 422.

{"enabled": true, "except": "store"}
// Response
{"changed": true, "slim": true}

Runs the script and answers when it ends. The bridge starts on its own. The answer is the map of extracted values itself, or null for a script with no extract steps. Runs are not saved. Needs the MobAI desktop app: a host started with mobai serve answers 503.

{"device_id": "00008101-001A0C3E1234", "params": {"query": "cats"}}
// Response
{"result": "cats"}

404: no such API or device. 422: the script failed, with the reason in error.

Every project folder with its tests. kind is mob, maestro, flow, js or config. missing: true marks a folder that no longer exists.

[{
  "dir": "/Users/you/code/shelf/tests",
  "name": "tests",
  "cases": [{"id": "auth/login.mob", "name": "login", "relPath": "auth/login.mob", "kind": "mob", "tags": ["smoke"], "modified": "2026-11-04T18:20:11Z"}]
}]

The project and the test file open in the app now. project_dir is null when no project is open.

{"project_dir": "/Users/you/code/shelf/tests", "open_file": "auth/login.mob"}

Adds a folder to Testing and makes it the open project. Answers 201.

{"dir": "/Users/you/code/shelf/tests"}
// Response
{"dir": "/Users/you/code/shelf/tests", "name": "tests"}

Runs one test and answers when it ends. The bridge starts on its own. The run is saved with the project's other runs. A failing test still answers 200, with passed: false. Answers 409 when a test already runs on the device.

{"project_dir": "/Users/you/code/shelf/tests", "case_path": "auth/login.mob", "device_id": "emulator-5554"}

// Response (trimmed)
{
  "caseId": "auth/login.mob",
  "caseName": "login",
  "deviceId": "emulator-5554",
  "deviceName": "Pixel 9",
  "startedAt": "2026-11-05T10:15:02Z",
  "finishedAt": "2026-11-05T10:15:19Z",
  "passed": false,
  "stepResults": [{"index": 0, "lineNumber": 4, "lineText": "tap \"Sign in\"", "passed": false, "startedAtMs": 0, "durationMs": 5012, "error": "..."}],
  "error": "...",
  "extracted": {"user": "ada"}
}

Answers when MobAI's API is up. requireDeviceClaim says whether callers must claim a device before driving it. headless is true for a host started with mobai serve. sharing says whether this computer shares its devices with other MobAI computers.

{
  "status": "ok",
  "service": "mobai",
  "hostname": "studio.local",
  "node_id": "...",
  "sharing": false,
  "requireDeviceClaim": false,
  "version": "4.0.0",
  "deviceCount": 2,
  "pid": 81234,
  "headless": false,
  "time": "2026-11-05T10:15:02Z"
}

An OpenAPI 3.0 document for the core device routes. Many routes on this page, such as web automation, metrics, debug sessions and simulators, are not in it.

A page in the browser for trying the routes in /openapi.json. It loads its viewer from the internet, so it needs a connection.