MobileDeviceSchema. API detail: Mobile devices.
create
POST /v1/mobile_devices. Every field is optional — an empty body gets an Android 15 phone in the us jurisdiction with a 10-minute idle timeout and a 2-hour ceiling. platform is android or ios, and model is phone. An iPhone has no os_version: omit it (it reads back null; sending one throws validation_failed). An Android phone usually boots in under a minute (a few with apps at create) and an iPhone in up to about three, so the answer is usually creating: poll get until it is ready. jurisdiction (us, eu, as) sets where the phone runs and the country of the residential IP its traffic exits through, with GPS, timezone, locale and carrier to match.
There is no limit on how many phones an organization runs, only on the balance: a create needs 10 minutes for every live phone and the new one at their rates (2,500 credits for one Android phone, 4,000 for one iPhone), plus what the live ones have run, or it throws insufficient_credits (402). It throws rate_limited (429) when the platform’s phones are all in use; try again shortly.
apps are installed from the app store when the phone starts: package names on Android, App Store bundle ids on iOS.
list
GET /v1/mobile_devices, cursor-paginated, terminated devices excluded; session_id narrows it to the phone that agent session opened. Reads rows only; see get for the reconciled read.
get
GET /v1/mobile_devices/{id}. Asks the provider and rewrites the row when they disagree — the read that notices an idle-timer termination.
update
PATCH /v1/mobile_devices/{id}. The name, and nothing else.
act
POST /v1/mobile_devices/{id}/act. One action; the device must be ready. image is { content_type: "image/jpeg", data: "<base64>" } on a screenshot, at half the screen’s resolution on Android and full resolution on an iPhone; its pixels map 1:1 to tap coordinates. Every other action answers image: null, so take a screenshot to see its result. press_key takes Android’s key names; an iPhone has no BACK or RECENTS, so navigate it with taps and HOME.
install_app installs an app from the app store onto the running phone (a package name or bundle id, as in apps). Its output is a MobileInstallAppOutput, { app, status, error }: installed, failed with an error, or installing when a large app outlasts the call’s minute — act again with the same app to check on it.
liveView
POST /v1/mobile_devices/{id}/live_view. Answers url, the device’s page on the dashboard, where the screen plays live. stream (a wss:// address and token for the dashboard’s player) is returned only to a signed-in member, so with an API key it is null: open url. Needs computers:write; a device still starting answers computer_unavailable, and one that has ended answers not_found.
stream is a bearer credential — whoever holds it drives the device until it ends. Do not log or store it; play it and let it die with the device. expires_at is null. Each mint is audited as mobile_device.live_view_opened, without the credential.
delete
DELETE /v1/mobile_devices/{id}. Ends the device; idempotent.